代理工具

因此，基本抽象不提供任何直接工具支持，但每个代理都可以选择它是否在构造时接受工具自定义。

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类。 这允许特定的代理实现接受特定于代理的按运行选项。

可以通过类为任何调用自定义ChatOptions基础IChatClientChatClientAgent。 ChatClientAgent可以接受ChatClientAgentRunOptions允许调用方为基础IChatClient.GetResponse方法提供ChatOptions的方法。 如果任何选项与在构造时提供给代理的选项发生冲突，则每个运行选项将优先。

使用此机制，我们可以提供每运行工具。

// 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. 使用 Web 搜索和 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 代理框架支持扩展代理功能的各种内置和托管工具：

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

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
)