Средства агента

Поэтому базовая абстракция не предоставляет никакой прямой поддержки инструментов, однако каждый агент может выбрать, принимает ли он настройку инструментов во время строительства.

Поддержка инструментов с помощью ChatClientAgent

Это ChatClientAgent класс агента, который можно использовать для создания агентических возможностей на основе любой службы вывода. Он поставляется с поддержкой:

1. Использование собственных средств функции с агентом
2. Использование встроенных средств, которые может поддерживать базовая служба.

Предоставление AIFunction экземпляров во время создания агента

Существуют различные способы создания ChatClientAgent, например напрямую или с помощью вспомогательных методов фабрики на различных клиентах служб, но все поддерживают передачу средств.

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

Предоставление AIFunction экземпляров при запуске агента

Хотя базовая AIAgent абстракция принимает AgentRunOptions методы выполнения, подклассы AIAgent могут принимать подклассы AgentRunOptions. Это позволяет определенным реализациям агента принимать определенные параметры для каждого запуска.

Базовый IChatClientChatClientAgent элемент можно настроить с помощью ChatOptions класса для любого вызова. Этот ChatClientAgent метод может принять, ChatClientAgentRunOptions что позволяет вызывающему объекту предоставлять ChatOptions базовый IChatClient.GetResponse метод. Где любой вариант столкновений с параметрами, предоставленными агенту во время строительства, варианты выполнения будут иметь приоритет.

С помощью этого механизма можно предоставить средства для каждого запуска.

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

Использование встроенных средств

Где базовая служба поддерживает встроенные средства, их можно предоставить с помощью тех же механизмов, что и описано выше.

Реализация IChatClient для базовой службы должна предоставлять производный AITool класс, который можно использовать для настройки встроенного средства.

Например, при создании агента Azure AI Foundry можно предоставить CodeInterpreterToolDefinition средство интерпретатора кода, встроенное в службу Azure AI Foundry.

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

Поддержка инструментов с помощью ChatAgent

Это ChatAgent класс агента, который можно использовать для создания агентических возможностей на основе любой службы вывода. Он поставляется с поддержкой:

1. Использование собственных средств функции с агентом
2. Использование встроенных средств, которые может поддерживать базовая служба.
3. Использование размещенных инструментов, таких как веб-поиск и серверы MCP (протокол контекста модели)

Предоставление средств функции во время создания агента

Существуют различные способы создания ChatAgentвспомогательных методов непосредственно или с помощью вспомогательных методов фабрики на различных клиентах служб. Все подходы поддерживают передачу инструментов во время строительства.

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

Агент автоматически будет использовать эти средства всякий раз, когда они необходимы для ответа на запросы пользователей:

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

Предоставление средств функции при запуске агента

Агенты Python поддерживают предоставление средств на основе каждого запуска с помощью tools параметра в обоих run() методах run_stream() . Если предоставляются средства уровня агента и уровня выполнения, они объединяются с инструментами на уровне выполнения, которые имеют приоритет.

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

Это также работает с потоковой передачей:

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

Использование встроенных и размещенных средств

Платформа агента Python поддерживает различные встроенные и размещенные средства, расширяющие возможности агента:

Средство поиска в Интернете

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 (протокол контекста модели)

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

Средство поиска файлов

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

Средство интерпретатора кода

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

Сочетание средств уровня агента и запуска

Средства, определенные на уровне агента, можно объединить с инструментами, предоставляемыми во время выполнения:

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