エージェントツール

ツールのサポートは、エージェントの種類によって大きく異なる場合があります。一部のエージェントでは、開発者は、外部関数ツールを提供するか、エージェントでサポートされている特定の組み込みツールをアクティブ化することを選択することで、構築時にエージェントをカスタマイズできます。一方、一部のカスタムエージェントでは、外部ツールを提供したり、組み込みツールをアクティブ化したりしてカスタマイズをサポートしない場合があります (変更すべきではない定義済みの機能が既に提供されている場合)。

そのため、基本抽象化では直接のツールサポートは提供されませんが、各エージェントは、構築時にツールのカスタマイズを受け入れるかどうかを選択できます。

ChatClientAgent でのツールのサポート

ChatClientAgentは、任意の推論サービスの上にエージェント機能を構築するために使用できるエージェントクラスです。次のサポートが付属しています。

エージェントで独自の関数ツールを使用する
基になるサービスでサポートされる可能性がある組み込みツールの使用。

ヒント

ChatClientAgentとサポートされているサービスの詳細については、「推論サービスに基づく単純なエージェント」を参照してください。

エージェントの構築中に `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のサブクラスを受け取ることができます。これにより、特定のエージェント実装で、エージェント固有の実行ごとのオプションを受け入れることが可能になります。

IChatClientの基になるChatClientAgentは、任意の呼び出しに対して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 エージェントを作成するときに、Azure AI Foundry サービスに組み込まれているコードインタープリターツールを有効にする CodeInterpreterToolDefinition を提供できます。

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

ChatAgent でのツールのサポート

ChatAgentは、任意の推論サービスの上にエージェント機能を構築するために使用できるエージェントクラスです。次のサポートが付属しています。

エージェントで独自の関数ツールを使用する
基になるサービスでサポートされる可能性がある組み込みツールの使用
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 Agent Framework では、エージェント機能を拡張するさまざまな組み込みツールとホスト型ツールがサポートされています。

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
)

注

ツールのサポートは、サービスプロバイダーによって異なります。 Azure AI などの一部のサービスでは、ホストされているツールがネイティブでサポートされますが、別のサービスでは異なるアプローチが必要な場合があります。特定のツール機能については、サービスプロバイダーのドキュメントを常に確認してください。

次のステップ

エージェント取得拡張生成

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-10-01

次の方法で共有

エージェント ツール