Ferramentas do Agente

Portanto, a abstração base não fornece suporte direto a ferramentas, no entanto, cada agente pode escolher se aceita a personalização de ferramentas no momento da construção.

Suporte a ferramentas com ChatClientAgent

É ChatClientAgent uma classe de agente que pode ser usada para criar recursos de agente com base em qualquer serviço de inferência. Ele vem com suporte para:

1. Usando suas próprias ferramentas de função com o agente
2. Usar ferramentas internas às quais o serviço subjacente pode dar suporte.

Fornecer AIFunction instâncias durante a construção do agente

Há várias maneiras de construir um ChatClientAgent, por exemplo, diretamente ou por meio de métodos auxiliares de fábrica em vários clientes de serviço, mas todos dão suporte à passagem de ferramentas.

// 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)]);

Fornecer AIFunction instâncias ao executar o agente

Embora a abstração base AIAgent aceite em seus métodos AgentRunOptions de execução, subclasses de AIAgent podem aceitar subclasses de AgentRunOptions. Isso permite que implementações de agente específicas aceitem opções específicas por execução do agente.

O subjacente IChatClient do ChatClientAgent pode ser personalizado por meio da ChatOptions classe para qualquer invocação. Pode ChatClientAgent aceitar um ChatClientAgentRunOptions que permite que o chamador forneça ChatOptions o método subjacente IChatClient.GetResponse . Quando qualquer opção entra em conflito com as opções fornecidas ao agente no momento da construção, as opções por execução terão precedência.

Usando esse mecanismo, podemos fornecer ferramentas por execução.

// 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));

Usando ferramentas internas

Quando o serviço subjacente dá suporte a ferramentas internas, eles podem ser fornecidos usando os mesmos mecanismos descritos acima.

A implementação do IChatClient para o serviço subjacente deve expor uma AITool classe derivada que pode ser usada para configurar a ferramenta interna.

Por exemplo, ao criar um Azure AI Foundry Agent, você pode fornecer uma CodeInterpreterToolDefinition ferramenta para habilitar o interpretador de código que é integrado ao serviço Azure AI Foundry.

var agent = await azureAgentClient.CreateAIAgentAsync(
    deploymentName,
    instructions: "You are a helpful assistant",
    tools: [new CodeInterpreterToolDefinition()]);

Suporte a ferramentas com ChatAgent

É ChatAgent uma classe de agente que pode ser usada para criar recursos de agente com base em qualquer serviço de inferência. Ele vem com suporte para:

1. Usando suas próprias ferramentas de função com o agente
2. Usar ferramentas internas às quais o serviço subjacente pode dar suporte
3. Usando ferramentas hospedadas, como pesquisa na Web e servidores MCP (Protocolo de Contexto de Modelo)

Fornecer ferramentas de função durante a construção do agente

Há várias maneiras de construir um ChatAgentmétodo auxiliar de fábrica ou diretamente em vários clientes de serviço. Todas as abordagens dão suporte a ferramentas de passagem em tempo de construção.

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]
)

O agente usará essas ferramentas automaticamente sempre que for necessário para responder às consultas de usuário:

result = await agent.run("What's the weather like in Amsterdam?")
print(result.text)  # The agent will call get_weather() function

Fornecer ferramentas de função ao executar o agente

Os agentes do Python dão suporte ao fornecimento de ferramentas por execução usando o tools parâmetro em ambos e run()run_stream() métodos. Quando ferramentas de nível de agente e de nível de execução são fornecidas, elas são combinadas, com ferramentas de nível de execução tendo precedência.

# 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
)

Isso também funciona com 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)

Usando ferramentas internas e hospedadas

O Python Agent Framework dá suporte a várias ferramentas internas e hospedadas que estendem os recursos do agente:

Ferramenta de Pesquisa na 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?")

Ferramentas 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://v4.hkg1.meaqua.org/api/mcp"
        )
    ]
)

result = await agent.run("How do I create an Azure storage account?")

Ferramenta de Pesquisa de Arquivos

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")

Ferramenta interpretador 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")

Combinando ferramentas de nível de agente e de nível de execução

Você pode combinar ferramentas definidas no nível do agente com as ferramentas fornecidas no runtime:

# 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
)