에이전트 도구

따라서 기본 추상화는 직접적인 도구 지원을 제공하지 않지만 각 에이전트는 생성 시 도구 사용자 지정을 허용할지 여부를 선택할 수 있습니다.

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수락할 수 있습니다. 이렇게 하면 특정 에이전트 구현에서 실행당 특정 에이전트 옵션을 수락할 수 있습니다.

호출에 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 추 서비스 위에 에이전트 기능을 빌드하는 데 사용할 수 있는 에이전트 클래스입니다. 다음을 지원합니다.

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 에이전트는 두 메서드 모두에서 toolsrun() 매개 변수를 사용하여 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
)