Megosztás:

Ügynökeszközök

Az eszköztámogatás jelentősen eltérhet a különböző ügynöktípusoktól. Egyes ügynökök lehetővé teszik a fejlesztők számára az ügynök testreszabását az építkezés során külső függvényeszközök biztosításával vagy az ügynök által támogatott speciális beépített eszközök aktiválásával. Másfelől előfordulhat, hogy egyes egyéni ügynökök nem támogatják a testreszabást külső vagy beépített eszközök aktiválásával, ha már rendelkeznek olyan meghatározott funkciókkal, amelyeket nem kellene módosítani.

Ezért az alap absztrakció nem nyújt közvetlen eszköztámogatást, azonban minden ügynök eldöntheti, hogy elfogadja-e az eszköz testreszabását az építéskor.

Eszköztámogatás a ChatClientAgenttel

Ez ChatClientAgent egy ügynökosztály, amely bármely következtetési szolgáltatáson felül ügynöki képességek létrehozására használható. Az alábbiakat támogatja:

  1. Saját függvényeszközök használata az ügynökkel
  2. Az alapul szolgáló szolgáltatás által támogatott beépített eszközök használata.

Jótanács

A támogatott szolgáltatásokról ChatClientAgent és információkról további információt a következtetési szolgáltatásokon alapuló Egyszerű ügynökök című témakörben talál.

Példányok biztosítása AIFunction az ügynök felépítése során

Különböző módokon hozhat létre ChatClientAgentpéldául közvetlenül vagy gyári segédmeterelyeket a különböző szolgáltatási ügyfeleken, de az összes támogatja az átadási eszközöket.

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

Példányok megadása AIFunction az ügynök futtatásakor

Bár az alap AIAgent absztrakció elfogadja a futtatási metódusokat AgentRunOptions , az AIAgent alosztályok a AgentRunOptions. Ez lehetővé teszi, hogy az adott ügynök-implementációk futásonként fogadjanak el ügynökspecifikus beállításokat.

A mögöttes IChatClientChatClientAgent az osztályon keresztül ChatOptions testre szabható bármilyen meghíváshoz. A ChatClientAgent can accept a ChatClientAgentRunOptions , amely lehetővé teszi a hívó számára, hogy a ChatOptions mögöttes IChatClient.GetResponse módszer. Ha bármely lehetőség ütközik az ügynöknek az építési időpontban megadott beállításokkal, a futtatási beállítások elsőbbséget élveznek.

Ezzel a mechanizmussal futtatásonkénti eszközöket biztosíthat.

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

Megjegyzés:

Nem minden ügynök támogatja az eszközhívást, ezért a futtatásonkénti eszközök biztosításához egy ügynökspecifikus beállításosztályt kell megadni.

Beépített eszközök használata

Ha a mögöttes szolgáltatás támogatja a beépített eszközöket, azokat a fent ismertetett mechanizmusokkal lehet biztosítani.

Az alapul szolgáló szolgáltatás IChatClient-implementációjának közzé kell tennie egy AITool származtatott osztályt, amely a beépített eszköz konfigurálásához használható.

Azure AI Foundry-ügynök létrehozásakor például engedélyezheti CodeInterpreterToolDefinition az Azure AI Foundry szolgáltatásba beépített kódértelmező eszközt.

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

Eszköztámogatás a ChatAgenttel

Ez ChatAgent egy ügynökosztály, amely bármely következtetési szolgáltatáson felül ügynöki képességek létrehozására használható. Az alábbiakat támogatja:

  1. Saját függvényeszközök használata az ügynökkel
  2. A mögöttes szolgáltatás által támogatott beépített eszközök használata
  3. Üzemeltetett eszközök, például webkeresés és MCP (Model Context Protocol) kiszolgálók használata

Függvényeszközök biztosítása az ügynöképítés során

A különböző szolgáltatási ügyfeleken különböző módokon hozhat létre ChatAgent– akár közvetlenül, akár gyári segédmetekénti módszerekkel . Minden megközelítés támogatja az átmenő eszközöket az építkezéskor.

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

Az ügynök automatikusan ezeket az eszközöket fogja használni, amikor szükség van rájuk a felhasználói lekérdezések megválaszolásához:

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

Függvényeszközök biztosítása az ügynök futtatásakor

A Python-ügynökök támogatják az eszközök futásonkénti biztosítását a paraméterrel mind toolsrun() a run_stream() metódusokban. Az ügynökszintű és a futtató szintű eszközök együttes használata esetén a futtató szintű eszközök elsőbbséget élveznek.

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

Ez a streameléssel is működik:

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

Beépített és üzemeltetett eszközök használata

A Python Agent Framework különböző beépített és üzemeltetett eszközöket támogat, amelyek kibővítik az ügynök képességeit:

Webes keresőeszköz

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 Context Protocol) eszközök

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

Fájlkereső eszköz

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

Kódértelmező eszköz

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

Ügynökszintű és futtató szintű eszközök keverése

Az ügynökszinten definiált eszközöket a futtatókörnyezetben biztosított eszközökkel kombinálhatja:

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

Megjegyzés:

Az eszköztámogatás szolgáltatónként eltérő. Egyes szolgáltatások, például az Azure AI natív módon támogatják a üzemeltetett eszközöket, míg mások eltérő megközelítéseket igényelhetnek. Mindig ellenőrizze a szolgáltató dokumentációjában az adott eszközképességeket.

Következő lépések

Ügynök lekérése bővített generáció

  • Last updated on