Använda funktionsverktyg med en agent

Det här självstudiesteget visar hur du använder funktionsverktyg med en agent, där agenten bygger på tjänsten Azure OpenAI Chat Completion.

Viktigt!

Alla agenttyper stöder inte funktionsverktyg. Vissa kanske bara stöder anpassade inbyggda verktyg, utan att anroparen kan tillhandahålla sina egna funktioner. Det här steget använder en ChatClientAgent, som stöder funktionsverktyg.

Förutsättningar

Förutsättningar och installation av NuGet-paket finns i steget Skapa och kör en enkel agent i den här självstudien.

Skapa agenten med funktionsverktyg

Funktionsverktyg är bara anpassad kod som du vill att agenten ska kunna anropa när det behövs. Du kan omvandla valfri C#-metod till ett funktionsverktyg genom att använda AIFunctionFactory.Create metoden för att skapa en AIFunction instans från metoden.

Om du behöver ange ytterligare beskrivningar om funktionen eller dess parametrar för agenten, så att den kan välja mellan olika funktioner mer exakt, kan du använda System.ComponentModel.DescriptionAttribute attributet för metoden och dess parametrar.

Här är ett exempel på ett enkelt funktionsverktyg som förfalskar att få vädret för en viss plats. Den är dekorerad med beskrivningsattribut för att ge ytterligare beskrivningar om sig själv och sin platsparameter för agenten.

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

När du skapar agenten kan du nu tillhandahålla funktionsverktyget till agenten genom att skicka en lista med verktyg till CreateAIAgent metoden.

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 kan du bara köra agenten som vanligt, så kan agenten anropa GetWeather funktionsverktyget när det behövs.

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

Viktigt!

Alla agenttyper stöder inte funktionsverktyg. Vissa kanske bara stöder anpassade inbyggda verktyg, utan att anroparen kan tillhandahålla sina egna funktioner. I det här steget används agenter som skapats via chattklienter, som stöder funktionsverktyg.

Förutsättningar

Förutsättningar och installation av Python-paket finns i steget Skapa och kör en enkel agent i den här självstudien.

Skapa agenten med funktionsverktyg

Funktionsverktyg är bara anpassad kod som du vill att agenten ska kunna anropa när det behövs. Du kan omvandla valfri Python-funktion till ett funktionsverktyg genom att skicka den till agentens tools parameter när du skapar agenten.

Om du behöver ange ytterligare beskrivningar om funktionen eller dess parametrar för agenten, så att den kan välja mellan olika funktioner mer exakt, kan du använda Pythons typanteckningar med Annotated och Pydantics Field för att ange beskrivningar.

Här är ett exempel på ett enkelt funktionsverktyg som förfalskar att få vädret för en viss plats. Den använder typanteckningar för att ge ytterligare beskrivningar om funktionen och dess platsparameter till agenten.

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

Du kan också använda dekoratören ai_function för att uttryckligen ange funktionens namn och beskrivning:

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

Om du inte anger parametrarna name och description i dekoratören ai_function använder ramverket automatiskt funktionens namn och dokumentsträng som återställningar.

När du skapar agenten kan du nu tillhandahålla funktionsverktyget till agenten genom att skicka det till parametern 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
)

Nu kan du bara köra agenten som vanligt, så kan agenten anropa get_weather funktionsverktyget när det behövs.

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

asyncio.run(main())

Skapa en klass med flera funktionsverktyg

Du kan också skapa en klass som innehåller flera funktionsverktyg som metoder. Detta kan vara användbart för att organisera relaterade funktioner tillsammans eller när du vill skicka tillstånd mellan dem.

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

När du skapar agenten kan du nu ange alla metoder för klassen som funktioner:

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

Du kan också dekorera funktionerna med samma ai_function dekoratör som tidigare.

Nästa steg

Använda funktionella verktyg med godkännanden där människor är involverade i processen