Bagikan melalui

Alat Agen

Dukungan alat dapat sangat bervariasi di antara berbagai jenis agen. Beberapa agen mungkin memungkinkan pengembang untuk menyesuaikan agen pada waktu konstruksi dengan menyediakan alat fungsi eksternal atau dengan memilih untuk mengaktifkan alat bawaan tertentu yang didukung oleh agen. Di sisi lain, beberapa agen kustom mungkin tidak mendukung penyesuaian melalui penyediaan alat bawaan eksternal atau aktivasi, jika mereka sudah menyediakan fitur yang ditentukan yang seharusnya tidak diubah.

Oleh karena itu, abstraksi dasar tidak memberikan dukungan alat langsung, namun setiap agen dapat memilih apakah ia menerima kustomisasi alat pada waktu konstruksi.

Dukungan alat dengan ChatClientAgent

ChatClientAgent adalah kelas agen yang dapat digunakan untuk membangun kemampuan agenik di atas layanan inferensi apa pun. Muncul dengan dukungan untuk:

  1. Menggunakan alat fungsi Anda sendiri dengan agen
  2. Menggunakan alat bawaan yang mungkin didukung oleh layanan yang mendasar.

Tip

Untuk informasi selengkapnya tentang dan informasi tentang ChatClientAgent layanan yang didukung, lihat Agen sederhana berdasarkan layanan inferensi

Menyediakan AIFunction instans selama konstruksi agen

Ada berbagai cara untuk membangun ChatClientAgent, misalnya, secara langsung atau melalui metode pembantu pabrik pada berbagai klien layanan, tetapi semua mendukung alat passing.

// 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.AsAIAgent(
    instructions: "You are a helpful assistant",
    tools: [AIFunctionFactory.Create(GetWeather)]);

Menyediakan AIFunction instans saat menjalankan agen

Sementara abstraksi dasar AIAgent menerima AgentRunOptions metode eksekusinya, subkelas AIAgent dapat menerima subkelas dari AgentRunOptions. Ini memungkinkan implementasi agen tertentu untuk menerima opsi per-eksekusi khusus agen.

Yang mendasar IChatClientChatClientAgent dari dapat disesuaikan melalui ChatOptions kelas untuk pemanggilan apa pun. ChatClientAgent dapat menerima yang ChatClientAgentRunOptions memungkinkan pemanggil untuk menyediakan ChatOptions metode yang mendasarIChatClient.GetResponse. Jika opsi apa pun berbenturan dengan opsi yang diberikan kepada agen pada waktu konstruksi, opsi per eksekusi akan diutamakan.

Dengan menggunakan mekanisme ini, Anda dapat menyediakan alat per-eksekusi.

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

Nota

Tidak semua agen mendukung panggilan alat, jadi menyediakan alat per eksekusi memerlukan penyediaan kelas opsi khusus agen.

Menggunakan alat bawaan

Di mana layanan yang mendasar mendukung alat bawaan, mereka dapat disediakan menggunakan mekanisme yang sama seperti yang dijelaskan di atas.

Implementasi IChatClient untuk layanan yang mendasar harus mengekspos AITool kelas turunan yang dapat digunakan untuk mengonfigurasi alat bawaan.

Misalnya, saat membuat Agen Azure AI Foundry, Anda dapat menyediakan CodeInterpreterToolDefinition untuk mengaktifkan alat penerjemah kode yang dibangun ke dalam layanan Azure AI Foundry.

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

Dukungan alat dengan ChatAgent

ChatAgent adalah kelas agen yang dapat digunakan untuk membangun kemampuan agenik di atas layanan inferensi apa pun. Muncul dengan dukungan untuk:

  1. Menggunakan alat fungsi Anda sendiri dengan agen
  2. Menggunakan alat bawaan yang mungkin didukung oleh layanan yang mendasar
  3. Menggunakan alat yang dihosting seperti pencarian web dan server MCP (Model Context Protocol)

Menyediakan alat fungsi selama konstruksi agen

Ada berbagai cara untuk membangun ChatAgent, baik secara langsung atau melalui metode pembantu pabrik pada berbagai klien layanan. Semua pendekatan mendukung alat yang melewati pada waktu konstruksi.

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().as_agent(
    instructions="You are a helpful assistant",
    tools=[get_weather]
)

Agen akan secara otomatis menggunakan alat-alat ini setiap kali diperlukan untuk menjawab kueri pengguna:

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

Menyediakan alat fungsi saat menjalankan agen

Agen Python mendukung penyediaan alat berdasarkan per-eksekusi menggunakan tools parameter dalam metode run() dan run_stream() . Ketika alat tingkat agen dan tingkat eksekusi disediakan, alat tersebut dikombinasikan, dengan alat tingkat eksekusi yang diutamakan.

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

Ini juga berfungsi dengan streaming:

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

Menggunakan alat bawaan dan yang dihosting

Python Agent Framework mendukung berbagai alat bawaan dan yang dihosting yang memperluas kemampuan agen:

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

Alat MCP (Protokol Konteks Model)

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

Alat Pencarian File

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

Alat Penerjemah Kode

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

Mencampur alat tingkat agen dan tingkat eksekusi

Anda dapat menggabungkan alat yang ditentukan di tingkat agen dengan alat yang disediakan pada runtime:

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

Nota

Dukungan alat bervariasi menurut penyedia layanan. Beberapa layanan seperti Azure AI mendukung alat yang dihosting secara asli, sementara yang lain mungkin memerlukan pendekatan yang berbeda. Selalu periksa dokumentasi penyedia layanan Anda untuk kemampuan alat tertentu.

Langkah selanjutnya

Pembuatan Tertambung Pengambilan Agen

  • Last updated on