Używanie narzędzi funkcjonalnych z agentem

Wymagania wstępne

Aby uzyskać wymagania wstępne i zainstalować pakiety NuGet, zobacz krok Tworzenie i uruchamianie prostego agenta w tym samouczku.

Tworzenie agenta za pomocą narzędzi funkcji

Narzędzia funkcji to kod niestandardowy, który ma być wywoływany przez agenta w razie potrzeby. Dowolną metodę języka C# można przekształcić w funkcję narzędzia, używając metody AIFunctionFactory.Create, aby utworzyć wystąpienie AIFunction z tej metody.

Jeśli musisz podać agentowi dodatkowe opisy funkcji lub jej parametrów, aby mógł on dokładniej wybierać między różnymi funkcjami, możesz użyć atrybutu System.ComponentModel.DescriptionAttribute dla metody i jej parametrów.

Oto przykład prostego narzędzia funkcjonalnego, które symuluje pobieranie danych pogodowych dla danej lokalizacji. Jest on ozdobiony atrybutami opisu, aby udostępnić dodatkowe opisy dotyczące samego siebie i jego parametru lokalizacji agentowi.

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

Podczas tworzenia agenta możesz teraz udostępnić narzędzie funkcjonalności agentowi, poprzez przekazanie listy narzędzi do metody 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)]);

Teraz możesz po prostu uruchomić agenta jak zwykle, a agent będzie mógł wywołać funkcję GetWeather w razie potrzeby.

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

Wymagania wstępne

Aby uzyskać wymagania wstępne i zainstalować pakiety języka Python, zobacz krok Tworzenie i uruchamianie prostego agenta w tym samouczku.

Tworzenie agenta za pomocą narzędzi funkcji

Narzędzia funkcji to kod niestandardowy, który ma być wywoływany przez agenta w razie potrzeby. Dowolną funkcję języka Python można przekształcić w narzędzie funkcji, przekazując ją do parametru agenta tools podczas tworzenia agenta.

Jeśli potrzebujesz podać dodatkowe opisy dotyczące funkcji lub jej parametrów agentowi, aby mógł dokładniej wybrać między różnymi funkcjami, możesz użyć adnotacji typu w języku Python, korzystając z elementów Annotated oraz narzędzi Pydantic Field do przekazywania opisów.

Oto przykład prostego narzędzia funkcjonalnego, które symuluje pobieranie danych pogodowych dla danej lokalizacji. Używa adnotacji typu, aby udostępnić dodatkowe opisy dotyczące funkcji i parametru lokalizacji dla agenta.

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

Możesz również użyć dekoratora ai_function , aby jawnie określić nazwę i opis funkcji:

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

Jeśli nie określisz parametrów name i description w dekoratorze ai_function, framework automatycznie użyje nazwy funkcji i jej docstringa jako wartości domyślnych.

Podczas tworzenia agenta można teraz udostępnić agentowi narzędzie funkcji, przekazując je jako parametr 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
)

Teraz możesz po prostu uruchomić agenta w zwykły sposób, a w razie potrzeby będzie mógł wywołać narzędzie do funkcji get_weather.

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

asyncio.run(main())

Tworzenie klasy z wieloma narzędziami funkcji

Można również utworzyć klasę zawierającą wiele narzędzi funkcji jako metody. Może to być przydatne w przypadku organizowania powiązanych funkcji razem lub przekazywania stanu między 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."

Podczas tworzenia agenta można teraz podać wszystkie metody klasy jako funkcje:

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

Można również dekorować funkcje tym samym ai_function dekoratorem co wcześniej.