Integración de herramientas personalizadas
Las herramientas personalizadas de un agente se pueden definir de varias maneras, en función de lo que funcione mejor para su escenario. Es posible que su empresa ya tenga Azure Functions implementado para que el agente lo use o que una especificación pública de OpenAPI proporcione a su agente la funcionalidad que busca.
Llamada de funciones
La llamada a funciones permite a los agentes ejecutar funciones predefinidas dinámicamente en función de la entrada del usuario. Esta característica es ideal para escenarios en los que los agentes necesitan realizar tareas específicas, como recuperar datos o procesar consultas de usuario, y se pueden realizar en el código desde dentro del agente. La función puede llamar a otras API para obtener información adicional o iniciar un programa.
Ejemplo: Definición y uso de una función
Comience definiendo una función a la que puede llamar el agente. Por ejemplo, esta es una función de seguimiento de caídas de nieve falsa:
import json
def recent_snowfall(location: str) -> str:
"""
Fetches recent snowfall totals for a given location.
:param location: The city name.
:return: Snowfall details as a JSON string.
"""
mock_snow_data = {"Seattle": "0 inches", "Denver": "2 inches"}
snow = mock_snow_data.get(location, "Data not available.")
return json.dumps({"location": location, "snowfall": snow})
Registre la función con el agente mediante el SDK de Azure AI:
# Define a function tool for the model to use
function_tool = FunctionTool(
name="recent_snowfall",
parameters={
"type": "object",
"properties": {
"location": {"type": "string", "description": "The city name to check snowfall for."},
},
"required": ["location"],
"additionalProperties": False
},
description="Get recent snowfall totals for a given location.",
strict=True,
)
# Add the function tool to a list of tools for the agent
tools: list[Tool] = [function_tool]
# Create your agent with the toolset
agent = project_client.agents.create_version(
name="snowfall-agent",
definition=PromptAgentDefinition(
model="gpt-4.1",
instructions="You are a weather assistant tracking snowfall. Use the provided functions to answer questions.",
tools=tools,
)
)
El agente ahora puede llamar a recent_snowfall dinámicamente cuando determina que la indicación requiere información que la función puede obtener.
Funciones de Azure
Azure Functions proporciona funcionalidades informáticas sin servidor para el procesamiento en tiempo real. Esta integración es ideal para flujos de trabajo controlados por eventos, lo que permite a los agentes responder a desencadenadores como solicitudes HTTP o mensajes de cola.
Ejemplo: Uso de Azure Functions con un desencadenador de cola
En primer lugar, desarrolle e implemente la función de Azure. En este ejemplo, imagine que tenemos una función en nuestra suscripción de Azure para capturar la nieve de una ubicación determinada.
Cuando la Función de Azure esté en su lugar, intégrala y agréguela a la definición del agente como una herramienta de Función de Azure.
tool = AzureFunctionTool(
azure_function=AzureFunctionDefinition(
input_binding=AzureFunctionBinding(
storage_queue=AzureFunctionStorageQueue(
queue_name="STORAGE_INPUT_QUEUE_NAME",
queue_service_endpoint="STORAGE_QUEUE_SERVICE_ENDPOINT",
)
),
output_binding=AzureFunctionBinding(
storage_queue=AzureFunctionStorageQueue(
queue_name="STORAGE_OUTPUT_QUEUE_NAME",
queue_service_endpoint="STORAGE_QUEUE_SERVICE_ENDPOINT",
)
),
function=AzureFunctionDefinitionFunction(
name="queue_trigger",
description="Get weather for a given location",
parameters={
"type": "object",
"properties": {"location": {"type": "string", "description": "location to determine weather for"}},
},
),
)
)
agent = project_client.agents.create_version(
agent_name="MyAgent",
definition=PromptAgentDefinition(
model="gpt-4.1",
instructions="You are a helpful weather assistant. Use the provided Azure Function to get weather information for a location when needed.",
tools=[tool],
),
)
El agente ahora puede enviar solicitudes a la función de Azure a través de una cola de almacenamiento y procesar los resultados.
Especificación de OpenAPI
Las herramientas definidas por OpenAPI permiten a los agentes interactuar con las API externas mediante especificaciones estandarizadas. Este enfoque simplifica la integración de API y garantiza la compatibilidad con varios servicios. El servicio foundry Agent usa herramientas especificadas de OpenAPI 3.0.
Sugerencia
Actualmente, se admiten tres tipos de autenticación con herramientas de OpenAPI 3.0: anónima, clave de API e identidad administrada.
Ejemplo: Uso de una especificación de OpenAPI
En primer lugar, cree un archivo JSON ( en este ejemplo, denominado weather_openapi.json) que describa la API.
{
"openapi": "3.1.0",
"info": {
"title": "get weather data",
"description": "Retrieves current weather data for a location based on wttr.in.",
"version": "v1.0.0"
},
"servers": [
{
"url": "https://wttr.in"
}
],
"auth": [],
"paths": {
"/{location}": {
"get": {
"description": "Get weather information for a specific location",
"operationId": "GetCurrentWeather",
"parameters": [
{
"name": "location",
"in": "path",
"description": "City or location to retrieve the weather for",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "format",
"in": "query",
"description": "Always use j1 value for this parameter",
"required": true,
"schema": {
"type": "string",
"default": "j1"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Location not found"
}
},
"deprecated": false
}
}
},
"components": {
"schemes": {}
}
}
A continuación, registre la herramienta OpenAPI en la definición del agente:
from azure.ai.projects.models import OpenApiTool, OpenApiAnonymousAuthDetails
with open(weather_asset_file_path, "r") as f:
openapi_weather = cast(dict[str, Any], jsonref.loads(f.read()))
tool = OpenApiTool(
openapi=OpenApiFunctionDefinition(
name="get_weather",
spec=openapi_weather,
description="Retrieve weather information for a location.",
auth=OpenApiAnonymousAuthDetails(),
)
)
agent = project_client.agents.create_version(
agent_name="openapi-agent",
definition=PromptAgentDefinition(
model="gpt-4.1",
instructions="You are a weather assistant. Use the API to fetch weather data.",
tools=[openapi_tool],
),
)
El agente ahora puede usar la herramienta OpenAPI para capturar datos meteorológicos dinámicamente.
Nota:
Uno de los conceptos relacionados con agentes y herramientas personalizadas con los que los desarrolladores suelen tener dificultades es la naturaleza declarativa de la solución. No es necesario escribir código que llame explícitamente a las funciones personalizadas de la herramienta: el propio agente decide llamar a las funciones de la herramienta basándose en los mensajes de las indicaciones. Al proporcionar al agente funciones que tienen nombres significativos y parámetros bien documentados, el agente puede "averiguar" cuándo y cómo llamar a la función por sí mismo.
Mediante una de las opciones de herramientas personalizadas disponibles (o cualquier combinación de ellas), puede crear agentes eficaces, flexibles e inteligentes con foundry Agent Service. Estas integraciones permiten una interacción perfecta con sistemas externos, procesamiento en tiempo real y flujos de trabajo escalables, lo que facilita la creación de soluciones personalizadas adaptadas a sus necesidades.