Dela via

Agentverktyg

Stöd för verktyg kan variera avsevärt mellan olika agenttyper. Vissa agenter kan göra det möjligt för utvecklare att anpassa agenten vid byggtiden genom att tillhandahålla externa funktionsverktyg eller genom att välja att aktivera specifika inbyggda verktyg som stöds av agenten. Å andra sidan kan vissa anpassade agenter inte ha stöd för någon anpassning genom att tillhandahålla externa eller aktivera inbyggda verktyg, om de redan tillhandahåller definierade funktioner som inte bör ändras.

Därför tillhandahåller inte basabstraktionen något direkt verktygsstöd, men varje agent kan välja om den accepterar anpassning av verktyg vid byggtiden.

Stöd för verktyg med ChatClientAgent

ChatClientAgent är en agentklass som kan användas för att skapa agentiska funktioner ovanpå valfri slutsatsdragningstjänst. Den levereras med stöd för:

  1. Använda dina egna funktionsverktyg med agenten
  2. Använda inbyggda verktyg som den underliggande tjänsten kan stödja.

Tips/Råd

Mer information om och information om ChatClientAgent tjänster som stöds finns i Enkla agenter baserat på slutsatsdragningstjänster

Ange AIFunction instanser under agentkonstruktionen

Det finns olika sätt att skapa en ChatClientAgent, t.ex. direkt eller via fabrikshjälpmetoder på olika tjänstklienter, men alla stöder överföringsverktyg.

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

Ange AIFunction instanser när agenten körs

Även om basabstraktionen AIAgentAgentRunOptions accepterar på sina körningsmetoder kan underklasser av AIAgent acceptera underklasser av AgentRunOptions. Detta gör att specifika agentimplementeringar kan acceptera agentspecifika alternativ per körning.

IChatClient ChatClientAgent Underliggande för kan anpassas via ChatOptions klassen för valfritt anrop. ChatClientAgent Kan acceptera en ChatClientAgentRunOptions som gör att anroparen kan ange ChatOptions den underliggande IChatClient.GetResponse metoden. Om något alternativ krockar med alternativ som tillhandahålls agenten vid byggtiden har alternativen per körning företräde.

Med den här mekanismen kan vi tillhandahålla verktyg per körning.

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

Anmärkning

Det är inte alla agenter som stöder verktygssamtal, så för att tillhandahålla verktyg per körning krävs en agentspecifik alternativklass.

Använda inbyggda verktyg

Om den underliggande tjänsten stöder inbyggda verktyg kan de tillhandahållas med hjälp av samma mekanismer som beskrivs ovan.

IChatClient-implementeringen för den underliggande tjänsten bör exponera en AITool härledd klass som kan användas för att konfigurera det inbyggda verktyget.

När du till exempel skapar en Azure AI Foundry Agent kan du ange ett CodeInterpreterToolDefinition för att aktivera kodtolkarverktyget som är inbyggt i Azure AI Foundry-tjänsten.

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

Stöd för verktyg med ChatAgent

ChatAgent är en agentklass som kan användas för att skapa agentiska funktioner ovanpå valfri slutsatsdragningstjänst. Den levereras med stöd för:

  1. Använda dina egna funktionsverktyg med agenten
  2. Använda inbyggda verktyg som den underliggande tjänsten kan stödja
  3. Använda värdbaserade verktyg som webbsökning och MCP-servrar (Model Context Protocol)

Tillhandahålla funktionsverktyg under agentkonstruktionen

Det finns olika sätt att skapa en ChatAgent, antingen direkt eller via fabrikshjälpmetoder på olika tjänstklienter. Alla metoder stöder överföring av verktyg vid byggtid.

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

Agenten använder automatiskt dessa verktyg när de behövs för att besvara användarfrågor:

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

Tillhandahålla funktionsverktyg när agenten körs

Python-agenter har stöd för att tillhandahålla verktyg per körning med hjälp av parametern tools i både run() och run_stream() metoder. När både verktyg på agentnivå och körningsnivå tillhandahålls kombineras de med verktyg på körnivå som har företräde.

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

Detta fungerar också med strömning:

async for update in agent.run_stream(
    "Tell me about the weather",
    tools=[get_weather]
):
    if update.text:
        print(update.text, end="", flush=True)

Använda inbyggda och värdbaserade verktyg

Python Agent Framework stöder olika inbyggda och värdbaserade verktyg som utökar agentfunktionerna:

Webbsökningsverktyg

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

MCP-verktyg (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://learn.microsoft.com/api/mcp"
        )
    ]
)

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

Filsökningsverktyg

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

Kodtolkarverktyg

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

Blanda verktyg på agentnivå och körningsnivå

Du kan kombinera verktyg som definierats på agentnivå med verktyg som tillhandahålls vid körning:

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

Anmärkning

Verktygsstöd varierar beroende på tjänstleverantör. Vissa tjänster som Azure AI stöder värdbaserade verktyg internt, medan andra kan kräva olika metoder. Kontrollera alltid serviceleverantörens dokumentation för specifika verktygsfunktioner.

Nästa steg

Förhöjd generering av agenthämtning

  • Last updated on