Freigeben über

Agenttools

Die Toolunterstützung kann zwischen verschiedenen Agenttypen erheblich variieren. Einige Agents ermöglichen Entwicklern möglicherweise, den Agenten zur Bauzeit anzupassen, indem externe Funktionstools bereitgestellt werden, oder indem Sie bestimmte integrierte Tools aktivieren, die vom Agent unterstützt werden. Andererseits unterstützen einige benutzerdefinierte Agents möglicherweise keine Anpassungen, indem sie externe oder integrierte Tools bereitstellen, wenn sie bereits definierte Features bereitstellen, die nicht geändert werden sollten.

Daher bietet die Basisstraktion keine direkte Toolunterstützung, aber jeder Agent kann auswählen, ob die Anpassung der Tools zur Bauzeit akzeptiert wird.

Toolunterstützung mit ChatClientAgent

Dies ChatClientAgent ist eine Agentklasse, die verwendet werden kann, um agentische Funktionen über jeden Rückschlussdienst zu erstellen. Es bietet Unterstützung für:

  1. Verwenden Ihrer eigenen Funktionstools mit dem Agent
  2. Verwenden von integrierten Tools, die der zugrunde liegende Dienst unterstützen kann.

Tipp

Weitere Informationen und Informationen zu ChatClientAgent unterstützten Diensten finden Sie unter "Einfache Agents" basierend auf Denference-Diensten

Bereitstellen von AIFunction Instanzen während der Agent-Konstruktion

Es gibt verschiedene Möglichkeiten, z. B. direkt oder über Factoryhilfsmethoden auf verschiedenen Serviceclients zu erstellen ChatClientAgent, aber alle unterstützen das Übergeben von Tools.

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

Bereitstellen von AIFunction Instanzen beim Ausführen des Agents

Während die Basisstraktion AIAgent für die Ausführungsmethoden akzeptiertAgentRunOptions, können Unterklassen von AIAgent akzeptiert werden.AgentRunOptions Auf diese Weise können bestimmte Agentimplementierungen agentspezifische Optionen akzeptieren.

Die zugrunde liegende IChatClient Der ChatClientAgent kann über die ChatOptions Klasse für jeden Aufruf angepasst werden. Dies ChatClientAgent kann eine ChatClientAgentRunOptions Akzeptieren, mit der der Aufrufer die zugrunde liegende ChatOptions Methode bereitstellen IChatClient.GetResponse kann. Wenn jede Option mit optionen kollidiert, die dem Agenten zur Bauzeit zur Verfügung gestellt werden, haben die Optionen pro Ausführung Vorrang.

Mit diesem Mechanismus können wir tools pro Ausführung bereitstellen.

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

Hinweis

Nicht alle Agents unterstützen Toolanrufe, sodass die Bereitstellung von Tools pro Ausführung eine agentspezifische Optionsklasse erfordert.

Verwenden integrierter Tools

Wenn der zugrunde liegende Dienst integrierte Tools unterstützt, können sie mit denselben Mechanismen wie oben beschrieben bereitgestellt werden.

Die IChatClient-Implementierung für den zugrunde liegenden Dienst sollte eine abgeleitete AITool Klasse verfügbar machen, die zum Konfigurieren des integrierten Tools verwendet werden kann.

Wenn Sie z. B. einen Azure AI Foundry Agent erstellen, können Sie ein CodeInterpreterToolDefinition Tool zum Aktivieren des Codedolmetschertools bereitstellen, das in den Azure AI Foundry-Dienst integriert ist.

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

Toolunterstützung mit ChatAgent

Dies ChatAgent ist eine Agentklasse, die verwendet werden kann, um agentische Funktionen über jeden Rückschlussdienst zu erstellen. Es bietet Unterstützung für:

  1. Verwenden Ihrer eigenen Funktionstools mit dem Agent
  2. Verwenden von integrierten Tools, die der zugrunde liegende Dienst unterstützen kann
  3. Verwenden von gehosteten Tools wie Websuche und MCP-Servern (Model Context Protocol)

Bereitstellen von Funktionswerkzeugen während des Baumittels

Es gibt verschiedene Möglichkeiten, eine ChatAgent, entweder direkt oder über Factoryhilfsmethoden auf verschiedenen Dienstclients zu konstruieren. Alle Ansätze unterstützen das Übergeben von Werkzeugen zur Bauzeit.

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

Der Agent verwendet diese Tools automatisch, wenn er zur Beantwortung von Benutzerabfragen benötigt wird:

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

Bereitstellen von Funktionstools beim Ausführen des Agents

Python-Agents unterstützen die Bereitstellung von Tools pro Ausführung mithilfe des tools Parameters in beiden run() Methoden run_stream() . Wenn sowohl Tools auf Agentebene als auch auf Ausführungsebene bereitgestellt werden, werden sie kombiniert, wobei Tools auf Ausführungsebene Vorrang haben.

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

Dies funktioniert auch mit 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)

Verwenden integrierter und gehosteter Tools

Das Python Agent Framework unterstützt verschiedene integrierte und gehostete Tools, die Agentfunktionen erweitern:

Websuchtool

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

Dateisuche-Tool

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

Codedolmetschertool

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

Mischen von Tools auf Agentebene und Ausführungsebene

Sie können tools, die auf Agentebene definiert sind, mit Tools kombinieren, die zur Laufzeit bereitgestellt werden:

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

Hinweis

Die Toolunterstützung variiert je nach Dienstanbieter. Einige Dienste wie Azure AI unterstützen gehostete Tools nativ, während andere möglicherweise unterschiedliche Ansätze erfordern. Überprüfen Sie immer die Dokumentation Ihres Dienstanbieters auf bestimmte Toolfunktionen.

Nächste Schritte

Generierung erweiterter Agent-Abruf

  • Last updated on