Použití funkčních nástrojů s agentem

V tomto kurzu se dozvíte, jak používat nástroje funkcí s agentem, kde je agent založený na službě Dokončování chatu Azure OpenAI.

Důležité

Ne všechny typy agentů podporují funkční nástroje. Některé můžou podporovat jenom vlastní integrované nástroje, aniž by volající mohl poskytovat vlastní funkce. Tento krok používá ChatClientAgent, který podporuje funkční nástroje.

Požadavky

Informace o požadavcích a instalaci balíčků NuGet naleznete v kroku Vytvoření a spuštění jednoduchého agenta v tomto kurzu.

Vytvoření agenta pomocí nástrojů funkcí

Nástroje funkcí jsou jen vlastní kód, který může agent použít, když je to potřeba. Libovolnou metodu jazyka C# můžete převést na nástroj funkce pomocí AIFunctionFactory.Create metody k vytvoření AIFunction instance z této metody.

Pokud potřebujete do agenta zadat další popisy funkce nebo jeho parametrů, aby bylo možné přesněji zvolit mezi různými funkcemi, můžete použít System.ComponentModel.DescriptionAttribute atribut metody a jeho parametrů.

Tady je příklad jednoduchého funkčního nástroje, který zfalšuje počasí pro dané místo. Je opatřen atributy popisu, aby poskytoval další informace o sobě a parametru umístění agenta.

using System.ComponentModel;

[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.";

Při vytváření agenta teď můžete agentu poskytnout nástroj funkce předáním seznamu nástrojů metodě CreateAIAgent .

using System;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI;

AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new AzureCliCredential())
     .GetChatClient("gpt-4o-mini")
     .CreateAIAgent(instructions: "You are a helpful assistant", tools: [AIFunctionFactory.Create(GetWeather)]);

Nyní můžete agenta spustit obvyklým způsobem a agent bude moct v případě potřeby volat funkční nástroj GetWeather.

Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?"));

Důležité

Ne všechny typy agentů podporují funkční nástroje. Některé můžou podporovat jenom vlastní integrované nástroje, aniž by volající mohl poskytovat vlastní funkce. Tento krok využívá agenty vytvořené prostřednictvím chatovacích klientů, které podporují funkční nástroje.

Požadavky

Informace o požadavcích a instalaci balíčků Pythonu najdete v části Vytvoření a spuštění jednoduchého agenta v tomto kurzu.

Vytvoření agenta pomocí nástrojů funkcí

Nástroje funkcí jsou jen vlastní kód, který může agent použít, když je to potřeba. Libovolnou funkci Pythonu můžete převést na nástroj funkce tak, že ji při vytváření agenta tools předáte parametru agenta.

Pokud potřebujete do agenta zadat další popisy funkce nebo jeho parametrů, aby bylo možné přesněji zvolit mezi různými funkcemi, můžete k zadání popisů použít poznámky typu Pythonu a Annotated Pydantic Field .

Tady je příklad jednoduchého funkčního nástroje, který zfalšuje počasí pro dané místo. Poznámky typu se využívají k poskytnutí dodatečných popisů funkce a jejího parametru umístění agentovi.

from typing import Annotated
from pydantic import Field

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

Dekorátor můžete také použít ai_function k explicitní zadání názvu a popisu funkce:

from typing import Annotated
from pydantic import Field
from agent_framework import ai_function

@ai_function(name="weather_tool", description="Retrieves weather information for any location")
def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
) -> str:
    return f"The weather in {location} is cloudy with a high of 15°C."

Pokud v dekorátoru name nezadáte parametry description a ai_function, framework automaticky použije název funkce a docstring jako náhradní.

Při vytváření agenta teď můžete agentu poskytnout nástroj funkce tím, že ho předáte parametru tools .

import asyncio
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential

agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent(
    instructions="You are a helpful assistant",
    tools=get_weather
)

Teď můžete agenta spustit obvyklým způsobem a agent bude schopen v případě potřeby volat nástroj funkce get_weather.

async def main():
    result = await agent.run("What is the weather like in Amsterdam?")
    print(result.text)

asyncio.run(main())

Vytvoření třídy s více nástroji funkcí

Můžete také vytvořit třídu, která obsahuje více nástrojů funkcí jako metody. To může být užitečné pro uspořádání souvisejících funkcí pohromadě nebo při předávání stavu mezi nimi.

class WeatherTools:
    def __init__(self):
        self.last_location = None

    def get_weather(
        self,
        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."

    def get_weather_details(self) -> int:
        """Get the detailed weather for the last requested location."""
        if self.last_location is None:
            return "No location specified yet."
        return f"The detailed weather in {self.last_location} is cloudy with a high of 15°C, low of 7°C, and 60% humidity."

Při vytváření agenta teď můžete poskytnout všechny metody třídy jako funkce:

tools = WeatherTools()
agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent(
    instructions="You are a helpful assistant",
    tools=[tools.get_weather, tools.get_weather_details]
)

Můžete také ozdobit funkce stejným ai_function dekorátorem jako předtím.

Další kroky

Použití nástrojů funkce při schvalování za účasti lidí