Udostępnij przez

Narzędzia agenta

Obsługa narzędzi może się znacznie różnić między różnymi typami agentów. Niektórzy agenci mogą umożliwić deweloperom dostosowanie agenta w czasie budowy przez udostępnienie zewnętrznych narzędzi funkcji lub aktywowanie określonych wbudowanych narzędzi obsługiwanych przez agenta. Z drugiej strony niektórzy agenci niestandardowi mogą nie obsługiwać dostosowywania za pośrednictwem udostępniania zewnętrznych lub aktywowanych wbudowanych narzędzi, jeśli już udostępniają zdefiniowane funkcje, których nie należy zmieniać.

W związku z tym abstrakcja podstawowa nie zapewnia żadnej bezpośredniej obsługi narzędzi, jednak każdy agent może wybrać, czy akceptuje dostosowywanie narzędzi w czasie budowy.

Obsługa narzędzi za pomocą elementu ChatClientAgent

Jest ChatClientAgent to klasa agenta, która może służyć do tworzenia możliwości agenta na podstawie dowolnej usługi wnioskowania. Jest on dostarczany z obsługą:

  1. Korzystanie z własnych narzędzi funkcji z agentem
  2. Korzystanie z wbudowanych narzędzi, które może obsługiwać podstawowa usługa.

Wskazówka

Aby uzyskać więcej informacji na ChatClientAgent temat obsługiwanych usług i informacji na temat obsługiwanych usług, zobacz Proste agenty oparte na usługach wnioskowania

Udostępnianie AIFunction wystąpień podczas budowy agenta

Istnieją różne sposoby konstruowania ChatClientAgentmetody , np. bezpośrednio lub za pośrednictwem metod pomocnika fabryki na różnych klientach usług, ale wszystkie obsługują narzędzia przekazujące.

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

Udostępnianie AIFunction wystąpień podczas uruchamiania agenta

Chociaż abstrakcja podstawowa AIAgent akceptuje AgentRunOptions metody uruchamiania, podklasy AIAgent klasy mogą akceptować podklasy .AgentRunOptions Dzięki temu określone implementacje agentów mogą akceptować określone opcje poszczególnych przebiegów agenta.

Podstawy IChatClientChatClientAgent elementu można dostosować za pomocą ChatOptions klasy dla dowolnego wywołania. Obiekt ChatClientAgent może zaakceptować element ChatClientAgentRunOptions , który umożliwia obiektowi wywołującym podanie ChatOptions metody bazowej IChatClient.GetResponse . Jeśli każda opcja jest sprzeczna z opcjami dostarczonymi agentowi w czasie budowy, pierwszeństwo będą miały opcje dla poszczególnych przebiegów.

Korzystając z tego mechanizmu, możemy udostępnić narzędzia dla poszczególnych przebiegów.

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

Uwaga / Notatka

Nie wszyscy agenci obsługują wywoływanie narzędzi, dlatego udostępnianie narzędzi na przebieg wymaga udostępnienia klasy opcji specyficznych dla agenta.

Korzystanie z wbudowanych narzędzi

Jeśli podstawowa usługa obsługuje wbudowane narzędzia, można je udostępnić przy użyciu tych samych mechanizmów, jak opisano powyżej.

Implementacja IChatClient dla usługi bazowej powinna uwidocznić klasę pochodną AITool , która może służyć do konfigurowania wbudowanego narzędzia.

Na przykład podczas tworzenia agenta usługi Azure AI Foundry można podać element umożliwiający CodeInterpreterToolDefinition włączenie narzędzia interpretera kodu wbudowanego w usługę Azure AI Foundry.

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

Obsługa narzędzi w usłudze ChatAgent

Jest ChatAgent to klasa agenta, która może służyć do tworzenia możliwości agenta na podstawie dowolnej usługi wnioskowania. Jest on dostarczany z obsługą:

  1. Korzystanie z własnych narzędzi funkcji z agentem
  2. Korzystanie z wbudowanych narzędzi, które może obsługiwać podstawowa usługa
  3. Korzystanie z hostowanych narzędzi, takich jak wyszukiwanie w Internecie i serwery MCP (Model Context Protocol)

Udostępnianie narzędzi funkcji podczas budowy agenta

Istnieją różne sposoby konstruowania ChatAgentmetody pomocnika lub bezpośrednio lub za pośrednictwem metod pomocnika fabryki na różnych klientach usług. Wszystkie podejścia obsługują przekazywanie narzędzi w czasie budowy.

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

Agent będzie automatycznie używać tych narzędzi, gdy będą potrzebne do odpowiadania na zapytania użytkowników:

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

Udostępnianie narzędzi funkcji podczas uruchamiania agenta

Agenci języka Python obsługują dostarczanie narzędzi dla poszczególnych przebiegów przy użyciu parametru tools w obu run() metodach i run_stream() . Po udostępnieniu zarówno narzędzi na poziomie agenta, jak i na poziomie uruchamiania są one łączone, a narzędzia na poziomie uruchamiania mają pierwszeństwo.

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

Działa to również z przesyłaniem strumieniowym:

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

Korzystanie z wbudowanych i hostowanych narzędzi

Struktura agentów języka Python obsługuje różne wbudowane i hostowane narzędzia, które rozszerzają możliwości agenta:

Narzędzie wyszukiwania w Sieci 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?")

Narzędzia MCP (protokół kontekstu modelu)

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

Narzędzie wyszukiwania plików

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

Narzędzie interpretera kodu

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

Mieszanie narzędzi na poziomie agenta i na poziomie uruchamiania

Narzędzia zdefiniowane na poziomie agenta można łączyć z narzędziami udostępnianymi w czasie wykonywania:

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

Uwaga / Notatka

Obsługa narzędzi różni się w zależności od dostawcy usług. Niektóre usługi, takie jak Azure AI, obsługują narzędzia hostowane natywnie, a inne mogą wymagać różnych podejść. Zawsze sprawdzaj dokumentację dostawcy usług pod kątem określonych możliwości narzędzi.

Dalsze kroki

Generowanie rozszerzonego pobierania agenta

  • Last updated on