Ferramentas do agente

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

Suporte a ferramentas com ChatClientAgent

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

1. Usando suas próprias ferramentas de função com o agente
2. Usando ferramentas internas que o serviço subjacente pode suportar.

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

Existem várias maneiras de construir um ChatClientAgent, por exemplo, diretamente ou através de métodos auxiliares de fábrica em vários clientes de serviço, mas todos suportam ferramentas de passagem.

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

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

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

Usando este 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));

Utilização de ferramentas incorporadas

Quando o serviço subjacente suporta ferramentas integradas, elas podem ser fornecidas usando os mesmos mecanismos descritos acima.

A implementação 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 um CodeInterpreterToolDefinition para habilitar a ferramenta de interpretador de código que é incorporada 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 o ChatAgent

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

1. Usando suas próprias ferramentas de função com o agente
2. Usando ferramentas internas que o serviço subjacente pode suportar
3. Usando ferramentas hospedadas como pesquisa na Web e servidores MCP (Model Context Protocol)

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

Existem várias maneiras de construir um ChatAgent, diretamente ou através de métodos auxiliares de fábrica em vários clientes de serviço. Todas as abordagens suportam ferramentas de passagem no momento da 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á automaticamente essas ferramentas sempre que forem necessárias para responder às perguntas dos usuários:

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 Python suportam o fornecimento de ferramentas por execução usando o tools parâmetro em ambos os run()run_stream() métodos. Quando as ferramentas de nível de agente e de nível de execução são fornecidas, elas são combinadas, com as 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 integradas e hospedadas

O Python Agent Framework suporta 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 (Model Context Protocol)

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 ficheiros

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

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

Você pode combinar ferramentas definidas no nível do agente com ferramentas fornecidas em tempo de execução:

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