Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
La compatibilidad con herramientas puede variar considerablemente entre diferentes tipos de agente. Algunos agentes pueden permitir a los desarrolladores personalizar el agente en tiempo de construcción proporcionando herramientas de funciones externas o seleccionando activar herramientas integradas específicas compatibles con el agente. Por otro lado, algunos agentes personalizados pueden no admitir ninguna personalización a través de proporcionar herramientas integradas externas o activadas, si ya proporcionan características definidas que no deben cambiarse.
Por lo tanto, la abstracción base no proporciona compatibilidad con herramientas directas, pero cada agente puede elegir si acepta personalización de herramientas en tiempo de construcción.
Compatibilidad con herramientas con ChatClientAgent
ChatClientAgent es una clase de agente que se puede usar para crear funcionalidades agente sobre cualquier servicio de inferencia. Viene con compatibilidad con:
- Uso de sus propias herramientas de función con el agente
- Uso de herramientas integradas que el servicio subyacente puede admitir.
Sugerencia
Para obtener más información sobre ChatClientAgent los servicios admitidos e información sobre ellos, consulte Agentes simples basados en servicios de inferencia.
Proporcionar AIFunction instancias durante la construcción del agente
Hay varias maneras de construir , ChatClientAgentpor ejemplo, directamente o a través de métodos auxiliares de fábrica en varios clientes de servicio, pero todas admiten el paso de herramientas.
// Sample function tool.
[Description("Get the weather for a given location.")]
static string GetWeather([Description("The location to get the weather for.")] string location)
=> $"The weather in {location} is cloudy with a high of 15°C.";
// When calling the ChatClientAgent constructor.
new ChatClientAgent(
chatClient,
instructions: "You are a helpful assistant",
tools: [AIFunctionFactory.Create(GetWeather)]);
// When using one of the helper factory methods.
openAIResponseClient.CreateAIAgent(
instructions: "You are a helpful assistant",
tools: [AIFunctionFactory.Create(GetWeather)]);
Proporcionar AIFunction instancias al ejecutar el agente
Aunque la abstracción base AIAgent acepta AgentRunOptions en sus métodos de ejecución, las subclases de AIAgent pueden aceptar subclases de AgentRunOptions. Esto permite que las implementaciones específicas del agente acepten opciones específicas por ejecución del agente.
El subyacente IChatClient de se puede personalizar a través de ChatClientAgent la ChatOptions clase para cualquier invocación.
ChatClientAgent puede aceptar un objeto ChatClientAgentRunOptions que permite al autor de la llamada proporcionar ChatOptions el método subyacenteIChatClient.GetResponse. Cuando cualquier opción entre en conflicto con las opciones proporcionadas al agente en tiempo de construcción, las opciones por ejecución tendrán prioridad.
Con este mecanismo podemos proporcionar herramientas por ejecución.
// Create the chat options class with the per-run tools.
var chatOptions = new ChatOptions()
{
Tools = [AIFunctionFactory.Create(GetWeather)]
};
// Run the agent, with the per-run chat options.
await agent.RunAsync(
"What is the weather like in Amsterdam?",
options: new ChatClientAgentRunOptions(chatOptions));
Nota:
No todos los agentes admiten llamadas a herramientas, por lo que proporcionar herramientas por ejecución requiere proporcionar una clase de opciones específica del agente.
Uso de herramientas integradas
Cuando el servicio subyacente admite herramientas integradas, se pueden proporcionar con los mismos mecanismos que se describen anteriormente.
La implementación de IChatClient para el servicio subyacente debe exponer una AITool clase derivada que se puede usar para configurar la herramienta integrada.
Por ejemplo, al crear un agente de Azure AI Foundry, puede proporcionar un CodeInterpreterToolDefinition para habilitar la herramienta de intérprete de código integrada en el servicio Azure AI Foundry.
var agent = await azureAgentClient.CreateAIAgentAsync(
deploymentName,
instructions: "You are a helpful assistant",
tools: [new CodeInterpreterToolDefinition()]);
Compatibilidad con herramientas con ChatAgent
ChatAgent es una clase de agente que se puede usar para crear funcionalidades agente sobre cualquier servicio de inferencia. Viene con compatibilidad con:
- Uso de sus propias herramientas de función con el agente
- Uso de herramientas integradas que el servicio subyacente puede admitir
- Uso de herramientas hospedadas como servidores de búsqueda web y MCP (Protocolo de contexto de modelo)
Proporcionar herramientas de función durante la construcción del agente
Hay varias maneras de construir , ChatAgentya sea directamente o a través de métodos auxiliares de fábrica en varios clientes de servicio. Todos los enfoques admiten el paso de herramientas en tiempo de construcción.
from typing import Annotated
from pydantic import Field
from agent_framework import ChatAgent
from agent_framework.openai import OpenAIChatClient
# Sample function tool
def get_weather(
location: Annotated[str, Field(description="The location to get the weather for.")],
) -> str:
"""Get the weather for a given location."""
return f"The weather in {location} is cloudy with a high of 15°C."
# When creating a ChatAgent directly
agent = ChatAgent(
chat_client=OpenAIChatClient(),
instructions="You are a helpful assistant",
tools=[get_weather] # Tools provided at construction
)
# When using factory helper methods
agent = OpenAIChatClient().create_agent(
instructions="You are a helpful assistant",
tools=[get_weather]
)
El agente usará automáticamente estas herramientas siempre que sea necesario para responder a las consultas de usuario:
result = await agent.run("What's the weather like in Amsterdam?")
print(result.text) # The agent will call get_weather() function
Proporcionar herramientas de función al ejecutar el agente
Los agentes de Python admiten la prestación de herramientas por ejecución mediante el tools parámetro en ambos run() métodos y run_stream() . Cuando se proporcionan herramientas de nivel de agente y de nivel de ejecución, se combinan, con herramientas de nivel de ejecución que tienen prioridad.
# Agent created without tools
agent = ChatAgent(
chat_client=OpenAIChatClient(),
instructions="You are a helpful assistant"
# No tools defined here
)
# Provide tools for specific runs
result1 = await agent.run(
"What's the weather in Seattle?",
tools=[get_weather] # Tool provided for this run only
)
# Use different tools for different runs
result2 = await agent.run(
"What's the current time?",
tools=[get_time] # Different tool for this query
)
# Provide multiple tools for a single run
result3 = await agent.run(
"What's the weather and time in Chicago?",
tools=[get_weather, get_time] # Multiple tools
)
Esto también funciona con streaming:
async for update in agent.run_stream(
"Tell me about the weather",
tools=[get_weather]
):
if update.text:
print(update.text, end="", flush=True)
Uso de herramientas integradas y hospedadas
El marco del agente de Python admite varias herramientas integradas y hospedadas que amplían las funcionalidades del agente:
Herramienta de búsqueda web
from agent_framework import HostedWebSearchTool
agent = ChatAgent(
chat_client=OpenAIChatClient(),
instructions="You are a helpful assistant with web search capabilities",
tools=[
HostedWebSearchTool(
additional_properties={
"user_location": {
"city": "Seattle",
"country": "US"
}
}
)
]
)
result = await agent.run("What are the latest news about AI?")
Herramientas de MCP (Protocolo de contexto de modelo)
from agent_framework import HostedMCPTool
agent = ChatAgent(
chat_client=AzureAIAgentClient(async_credential=credential),
instructions="You are a documentation assistant",
tools=[
HostedMCPTool(
name="Microsoft Learn MCP",
url="https://learn.microsoft.com/api/mcp"
)
]
)
result = await agent.run("How do I create an Azure storage account?")
Herramienta de búsqueda de archivos
from agent_framework import HostedFileSearchTool, HostedVectorStoreContent
agent = ChatAgent(
chat_client=AzureAIAgentClient(async_credential=credential),
instructions="You are a document search assistant",
tools=[
HostedFileSearchTool(
inputs=[
HostedVectorStoreContent(vector_store_id="vs_123")
],
max_results=10
)
]
)
result = await agent.run("Find information about quarterly reports")
Herramienta de intérprete de código
from agent_framework import HostedCodeInterpreterTool
agent = ChatAgent(
chat_client=AzureAIAgentClient(async_credential=credential),
instructions="You are a data analysis assistant",
tools=[HostedCodeInterpreterTool()]
)
result = await agent.run("Analyze this dataset and create a visualization")
Combinación de herramientas de nivel de agente y de ejecución
Puede combinar herramientas definidas en el nivel de agente con herramientas proporcionadas en tiempo de ejecución:
# Agent with base tools
agent = ChatAgent(
chat_client=OpenAIChatClient(),
instructions="You are a helpful assistant",
tools=[get_time] # Base tool available for all runs
)
# This run has access to both get_time (agent-level) and get_weather (run-level)
result = await agent.run(
"What's the weather and time in New York?",
tools=[get_weather] # Additional tool for this run
)
Nota:
La compatibilidad con herramientas varía según el proveedor de servicios. Algunos servicios como Azure AI admiten herramientas hospedadas de forma nativa, mientras que otras pueden requerir enfoques diferentes. Compruebe siempre la documentación del proveedor de servicios para conocer las funcionalidades específicas de las herramientas.