Functiehulpprogramma's gebruiken met een agent

In deze zelfstudie leert u hoe u functiehulpprogramma's gebruikt met een agent, waarbij de agent is gebouwd op de Azure OpenAI Chat Completion-service.

Belangrijk

Niet alle agenttypen ondersteunen functiehulpprogramma's. Sommige bieden mogelijk alleen ondersteuning voor aangepaste ingebouwde hulpprogramma's, zonder dat de beller zijn eigen functies kan bieden. In deze stap wordt een ChatClientAgent gebruikt, dat wel functiehulpprogramma's ondersteunt.

Vereiste voorwaarden

Zie de stap Een eenvoudige agent maken en uitvoeren in deze zelfstudie voor vereisten en het installeren van NuGet-pakketten.

De agent maken met functiehulpprogramma's

Functiehulpprogramma's zijn alleen aangepaste code die u wilt dat de agent kan aanroepen wanneer dat nodig is. U kunt elke C#-methode omzetten in een functiehulpprogramma door de AIFunctionFactory.Create methode te gebruiken om een AIFunction exemplaar van de methode te maken.

Als u aanvullende beschrijvingen wilt opgeven over de functie of de bijbehorende parameters voor de agent, zodat deze nauwkeuriger kan kiezen tussen verschillende functies, kunt u het System.ComponentModel.DescriptionAttribute kenmerk voor de methode en de bijbehorende parameters gebruiken.

Hier volgt een voorbeeld van een eenvoudig hulpmiddel voor functies dat doet alsof het het weer voor een bepaalde locatie ophaalt. Het is ingericht met beschrijvingskenmerken om aanvullende beschrijvingen over zichzelf en de locatieparameter aan de agent te bieden.

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

Wanneer u de agent maakt, kunt u nu het functiehulpprogramma aan de agent doorgeven door een lijst met hulpprogramma's door te geven aan de CreateAIAgent methode.

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

Nu kunt u de agent gewoon als normaal uitvoeren en kan de agent het GetWeather functiehulpprogramma aanroepen wanneer dat nodig is.

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

Belangrijk

Niet alle agenttypen ondersteunen functiehulpprogramma's. Sommige bieden mogelijk alleen ondersteuning voor aangepaste ingebouwde hulpprogramma's, zonder dat de beller zijn eigen functies kan bieden. In deze stap worden agents gebruikt die zijn gemaakt via chatclients, die wel functiehulpprogramma's ondersteunen.

Vereiste voorwaarden

Zie de stap Een eenvoudige agent maken en uitvoeren in deze zelfstudie voor vereisten en het installeren van Python-pakketten.

De agent maken met functiehulpprogramma's

Functiehulpprogramma's zijn alleen aangepaste code die u wilt dat de agent kan aanroepen wanneer dat nodig is. U kunt elke Python-functie omzetten in een functie-instrument door deze door te geven aan de tools parameter van de agent bij het creëren van de agent.

Als u aanvullende beschrijvingen wilt opgeven over de functie of de bijbehorende parameters voor de agent, zodat deze nauwkeuriger kan kiezen tussen verschillende functies, kunt u de typeaantekeningen van Python gebruiken met Annotated en Pydantic's Field om beschrijvingen te bieden.

Hier volgt een voorbeeld van een eenvoudig hulpmiddel voor functies dat doet alsof het het weer voor een bepaalde locatie ophaalt. Er worden typeaantekeningen gebruikt om aanvullende beschrijvingen te geven over de functie en de locatieparameter voor de agent.

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

U kunt de ai_function decorator ook gebruiken om expliciet de naam en beschrijving van de functie op te geven:

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

Indien u de name en description parameters niet specificeert in de ai_function-decorator, gebruikt het framework automatisch de naam en de docstring van de functie als terugvalopties.

Wanneer u de agent maakt, kunt u nu het functiehulpprogramma aan de agent opgeven door deze door te geven aan de tools parameter.

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
)

Nu kunt u de agent gewoon als normaal uitvoeren en kan de agent het get_weather functiehulpprogramma aanroepen wanneer dat nodig is.

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

asyncio.run(main())

Een klasse maken met meerdere functiehulpprogramma's

U kunt ook een klasse maken die meerdere functiehulpprogramma's als methoden bevat. Dit kan handig zijn voor het ordenen van gerelateerde functies of wanneer u de status tussen deze functies wilt doorgeven.

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

Wanneer u de agent maakt, kunt u nu alle methoden van de klasse opgeven als functies:

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

U kunt de functies ook versieren met dezelfde ai_function decorator als voorheen.

Volgende stappen

Gebruik van functiehulpmiddelen met menselijke goedkeuring in de controlelus