Aracılığıyla paylaş

Aracı Araçları

Araç desteği farklı aracı türleri arasında önemli ölçüde farklılık gösterebilir. Bazı aracılar, geliştiricilerin dış işlev araçları sağlayarak veya aracı tarafından desteklenen belirli yerleşik araçları etkinleştirmeyi seçerek aracıyı oluşturma zamanında özelleştirmesine izin verebilir. Öte yandan bazı özel aracılar, değiştirilmemesi gereken tanımlı özellikler sağlıyorsa, harici araçlar sağlayarak veya yerleşik araçları etkinleştirerek özelleştirmeyi desteklemeyebilir.

Bu nedenle, temel soyutlama herhangi bir doğrudan araç desteği sağlamaz, ancak her aracı, yapım zamanında araç özelleştirmesini kabul edip etmeyeceğini seçebilir.

ChatClientAgent ile araç desteği

ChatClientAgent, herhangi bir çıkarım hizmetinin üzerinde aracı özellikleri oluşturmak için kullanılabilecek bir aracı sınıfıdır. Aşağıdakiler için destek sunulur:

  1. Aracıyla kendi işlev araçlarınızı kullanma
  2. Temel alınan hizmetin destekleyebilecekleri yerleşik araçları kullanma.

Tip

Desteklenen hizmetler hakkında ChatClientAgent daha fazla bilgi ve bilgi için bkz . Çıkarım hizmetlerine dayalı basit aracılar

Aracı oluşturma sırasında örnekler sağlama AIFunction

Örneğin, doğrudan veya çeşitli hizmet istemcilerinde fabrika yardımcı yöntemleri aracılığıyla oluşturmanın çeşitli yolları vardır ChatClientAgent, ancak bunların tümü geçiş araçlarını destekler.

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

Aracıyı çalıştırırken örnekler sağlama AIFunction

Temel AIAgent soyutlama çalıştırma yöntemlerinde kabul etse AgentRunOptions de, alt sınıfları AIAgent alt sınıflarını AgentRunOptionskabul edebilir. Bu, belirli aracı uygulamalarının çalıştır başına aracıya özgü seçenekleri kabul etmesine olanak tanır.

öğesinin IChatClient temeliChatClientAgent, herhangi bir çağrı için sınıfı aracılığıyla ChatOptions özelleştirilebilir. , ChatClientAgent çağıranın temel ChatClientAgentRunOptions alınan yöntemi sağlamasına ChatOptions olanak tanıyan bir IChatClient.GetResponse öğesini kabul edebilir. Herhangi bir seçenek, inşaat zamanında aracıya sağlanan seçeneklerle çakışırsa çalıştırma başına seçenekler öncelikli olur.

Bu mekanizmayı kullanarak çalıştırma başına araçlar sağlayabiliriz.

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

Uyarı

Aracıların tümü araç çağrısını desteklemez, bu nedenle çalıştırma başına araç sağlamak için aracıya özgü seçenekler sınıfı sağlanması gerekir.

Yerleşik araçları kullanma

Temel alınan hizmet yerleşik araçları desteklediğinde, bunlar yukarıda açıklandığı gibi aynı mekanizmalar kullanılarak sağlanabilir.

Temel alınan hizmet için IChatClient uygulaması, yerleşik aracı yapılandırmak için kullanılabilecek türetilmiş bir AITool sınıfı kullanıma sunmalıdır.

Örneğin, bir Azure AI Foundry Aracısı oluştururken, Azure AI Foundry hizmetinde yerleşik olarak bulunan kod yorumlayıcı aracını etkinleştirmek için bir CodeInterpreterToolDefinition sağlayabilirsiniz.

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

ChatAgent ile araç desteği

ChatAgent, herhangi bir çıkarım hizmetinin üzerinde aracı özellikleri oluşturmak için kullanılabilecek bir aracı sınıfıdır. Aşağıdakiler için destek sunulur:

  1. Aracıyla kendi işlev araçlarınızı kullanma
  2. Temel alınan hizmetin destekleyebilecekleri yerleşik araçları kullanma
  3. Web araması ve MCP (Model Bağlam Protokolü) sunucuları gibi barındırılan araçları kullanma

Aracı oluşturma sırasında işlev araçları sağlama

Doğrudan veya çeşitli hizmet istemcilerinde fabrika yardımcı yöntemleri aracılığıyla oluşturmanın ChatAgentçeşitli yolları vardır. Tüm yaklaşımlar, inşaat zamanında araçları geçirmeyi destekler.

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

Aracı, kullanıcı sorgularını yanıtlamak için gerekli olduğunda otomatik olarak bu araçları kullanır:

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

Aracıyı çalıştırırken işlev araçları sağlama

Python aracıları, hem hem tools de run() yöntemlerinde parametresini kullanarak çalıştırma başına araçlar sağlamayı run_stream() destekler. Hem aracı düzeyi hem de çalışma düzeyi araçları sağlandığında, bunlar, öncelik alan çalışma düzeyi araçlarla birleştirilir.

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

Bu, akışla da çalışır:

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

Yerleşik ve barındırılan araçları kullanma

Python Agent Framework, aracı özelliklerini genişleten çeşitli yerleşik ve barındırılan araçları destekler:

Web Arama Aracı

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 (Model Bağlam Protokolü) Araçları

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

Dosya Arama Aracı

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

Kod Yorumlayıcı Aracı

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

Aracı düzeyi ve çalışma düzeyi araçlarını karıştırma

Aracı düzeyinde tanımlanan araçları çalışma zamanında sağlanan araçlarla birleştirebilirsiniz:

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

Uyarı

Araç desteği hizmet sağlayıcısına göre değişir. Azure AI gibi bazı hizmetler barındırılan araçları yerel olarak desteklerken, diğerleri farklı yaklaşımlar gerektirebilir. Belirli araç özellikleri için her zaman hizmet sağlayıcınızın belgelerine bakın.

Sonraki Adımlar

Aracı Alma Artırılmış Oluşturma

  • Last updated on