Sdílet prostřednictvím

Nástroje agenta

Podpora nástrojů se může výrazně lišit mezi různými typy agentů. Někteří agenti můžou vývojářům umožnit přizpůsobení agenta v době výstavby tím, že poskytnou externí nástroje funkcí nebo se rozhodnete aktivovat konkrétní předdefinované nástroje, které agent podporuje. Na druhou stranu některé vlastní agenty nemusí podporovat žádné přizpůsobení prostřednictvím poskytování externích nebo aktivovaných integrovaných nástrojů, pokud už poskytují definované funkce, které by se neměly měnit.

Základní abstrakce proto neposkytuje žádnou přímou podporu nástrojů, ale každý agent může zvolit, zda přijímá přizpůsobení nástrojů v době výstavby.

Podpora nástrojů s ChatClientAgent

Jedná se ChatClientAgent o třídu agenta, která se dá použít k sestavení funkcí agentů na základě jakékoli služby odvozování. Dodává se s podporou pro:

  1. Použití vlastních nástrojů funkcí s agentem
  2. Použití integrovaných nástrojů, které může podkladová služba podporovat.

Návod

Další informace o ChatClientAgent podporovaných službách a informace o podporovaných službách najdete v tématu Jednoduché agenty založené na službách odvozování.

Poskytování AIFunction instancí během sestavování agentů

Existují různé způsoby, jak vytvořit ChatClientAgent, například přímo nebo prostřednictvím pomocných metod továrny na různých klientech služeb, ale všechny podporují předávání nástrojů.

// 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.AsAIAgent(
    instructions: "You are a helpful assistant",
    tools: [AIFunctionFactory.Create(GetWeather)]);

Poskytnutí AIFunction instancí při spuštění agenta

Zatímco základní AIAgent abstrakce přijímá AgentRunOptions pro své metody spuštění, podtřídy AIAgent mohou přijímat podtřídy .AgentRunOptions To umožňuje, aby konkrétní implementace agenta přijímaly možnosti specifické pro jednotlivé spuštění agenta.

IChatClient Podkladový ChatClientAgent objekt lze přizpůsobit prostřednictvím ChatOptions třídy pro jakékoli vyvolání. Může ChatClientAgent přijmout, ChatClientAgentRunOptions což volajícímu umožní zadat ChatOptions pro podkladovou IChatClient.GetResponse metodu. Pokud jakákoli možnost koliduje s možnostmi poskytnutými agentem v době výstavby, budou mít přednost možnosti jednotlivých spuštění.

Pomocí tohoto mechanismu můžete poskytovat nástroje pro jednotlivé spuště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));

Poznámka:

Ne všichni agenti podporují volání nástroje, takže poskytování nástrojů pro každé spuštění vyžaduje poskytnutí třídy možností specifických pro agenta.

Použití předdefinovaných nástrojů

Pokud podkladová služba podporuje integrované nástroje, je možné je poskytnout pomocí stejných mechanismů, jak je popsáno výše.

Implementace IChatClient pro podkladovou službu by měla zveřejnit odvozenou AITool třídu, kterou lze použít ke konfiguraci integrovaného nástroje.

Například při vytváření agenta Azure AI Foundry můžete poskytnout CodeInterpreterToolDefinition nástroj pro interpret kódu, který je integrovaný do služby Azure AI Foundry.

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

Podpora nástrojů s využitím ChatAgent

Jedná se ChatAgent o třídu agenta, která se dá použít k sestavení funkcí agentů na základě jakékoli služby odvozování. Dodává se s podporou pro:

  1. Použití vlastních nástrojů funkcí s agentem
  2. Použití integrovaných nástrojů, které může podkladová služba podporovat
  3. Použití hostovaných nástrojů, jako jsou webové vyhledávání a servery MCP (Model Context Protocol)

Poskytování nástrojů funkcí během sestavování agentů

Existují různé způsoby, jak vytvořit ChatAgent, buď přímo nebo prostřednictvím pomocných metod továrny na různých klientech služeb. Všechny přístupy podporují předávání nástrojů v době výstavby.

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().as_agent(
    instructions="You are a helpful assistant",
    tools=[get_weather]
)

Agent bude tyto nástroje automaticky používat vždy, když je potřeba, aby odpovídal na dotazy uživatelů:

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

Poskytnutí nástrojů funkcí při spuštění agenta

Agenti Pythonu podporují poskytování nástrojů pro jednotlivé spuštění pomocí parametru tools v obou run() i run_stream() metodách. Pokud jsou k dispozici nástroje na úrovni agenta i na úrovni spuštění, zkombinují se s nástroji na úrovni spuštění, které mají přednost.

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

Funguje to také se streamováním:

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

Použití integrovaných a hostovaných nástrojů

Python Agent Framework podporuje různé integrované a hostované nástroje, které rozšiřují možnosti agenta:

Nástroj pro vyhledávání na webu

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

Nástroje 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://learn.microsoft.com/api/mcp"
        )
    ]
)

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

Nástroj pro vyhledávání souborů

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

Nástroj Interpret kódu

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

Kombinování nástrojů na úrovni agenta a spuštění

Nástroje definované na úrovni agenta můžete kombinovat s nástroji poskytovanými za běhu:

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

Poznámka:

Podpora nástrojů se liší podle poskytovatele služeb. Některé služby, jako je Azure AI, nativně podporují hostované nástroje, zatímco jiné můžou vyžadovat různé přístupy. Vždy zkontrolujte konkrétní možnosti nástrojů v dokumentaci poskytovatele služeb.

Další kroky

Rozšířená generace načítání agenta

  • Last updated on