Verwenden von Funktionstools mit einem Agent

In diesem Lernprogrammschritt erfahren Sie, wie Sie Funktionstools mit einem Agent verwenden, in dem der Agent auf dem Azure OpenAI-Chat-Abschlussdienst basiert.

Von Bedeutung

Nicht alle Agenttypen unterstützen Funktionstools. Einige unterstützen möglicherweise nur benutzerdefinierte integrierte Tools, ohne dem Aufrufer die Bereitstellung eigener Funktionen zu gestatten. In diesem Schritt wird ein ChatClientAgent verwendet, der Funktionstools unterstützt.

Voraussetzungen

Die erforderlichen Komponenten und die Installation von NuGet-Paketen finden Sie im Abschnitt zum Erstellen und Ausführen eines einfachen Agent-Schritts in diesem Lernprogramm.

Erstellen Sie den Agenten mit Funktionstools

Funktionstools sind nur benutzerdefinierter Code, den der Agent bei Bedarf aufrufen soll. Sie können jede C#-Methode in ein Funktionstool umwandeln, indem Sie die AIFunctionFactory.Create Methode verwenden, um eine AIFunction Instanz aus der Methode zu erstellen.

Wenn Sie zusätzliche Beschreibungen über die Funktion oder deren Parameter für den Agent angeben müssen, damit sie genauer zwischen verschiedenen Funktionen wählen kann, können Sie das System.ComponentModel.DescriptionAttribute Attribut für die Methode und die zugehörigen Parameter verwenden.

Hier ist ein Beispiel für ein einfaches Funktionstool, das das Wetter für einen bestimmten Ort fälscht. Es ist mit Beschreibungsattributen versehen, um zusätzliche Beschreibungen über sich selbst und seinen Standortparameter für den Agent bereitzustellen.

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

Beim Erstellen des Agents können Sie nun das Funktionstool an den Agent bereitstellen, indem Sie eine Liste der Tools an die CreateAIAgent Methode übergeben.

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

Jetzt können Sie den Agent einfach normal ausführen, und der Agent kann das GetWeather Funktionstool bei Bedarf aufrufen.

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

Von Bedeutung

Nicht alle Agenttypen unterstützen Funktionstools. Einige unterstützen möglicherweise nur benutzerdefinierte integrierte Tools, ohne dem Aufrufer die Bereitstellung eigener Funktionen zu gestatten. In diesem Schritt werden Agents verwendet, die über Chatclients erstellt wurden, die Funktionstools unterstützen.

Voraussetzungen

Die erforderlichen Komponenten und die Installation von Python-Paketen finden Sie im Abschnitt zum Erstellen und Ausführen eines einfachen Agent-Schritts in diesem Lernprogramm.

Erstellen des Agents mit Funktionstools

Funktionstools sind nur benutzerdefinierter Code, den der Agent bei Bedarf aufrufen soll. Sie können jede Python-Funktion in ein Funktionstool umwandeln, indem Sie sie beim Erstellen des Agents an den Parameter des tools Agents übergeben.

Wenn Sie zusätzliche Beschreibungen zu der Funktion oder ihren Parametern für den Agent angeben müssen, damit sie genauer zwischen verschiedenen Funktionen wählen kann, können Sie die Python-Typanmerkungen mit Annotated und Pydantics Field verwenden, um Beschreibungen bereitzustellen.

Hier ist ein Beispiel für ein einfaches Funktionstool, das das Wetter für einen bestimmten Ort fälscht. Es verwendet Typanmerkungen, um zusätzliche Beschreibungen zu der Funktion und dem Positionsparameter für den Agent bereitzustellen.

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

Sie können auch den ai_function Dekorierer verwenden, um den Namen und die Beschreibung der Funktion explizit anzugeben:

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

Wenn Sie die Parameter name und description im ai_function Dekorateur nicht angeben, verwendet das Framework automatisch den Funktionsnamen und den Docstring als Fallbacks.

Beim Erstellen des Agents können Sie nun das Funktionstool an den Agent bereitstellen, indem Sie ihn an den tools Parameter übergeben.

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
)

Jetzt können Sie den Agent einfach normal ausführen, und der Agent kann das get_weather Funktionstool bei Bedarf aufrufen.

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

asyncio.run(main())

Erstellen einer Klasse mit mehreren Funktionstools

Sie können auch eine Klasse erstellen, die mehrere Funktionstools als Methoden enthält. Dies kann nützlich sein, um verwandte Funktionen zusammen zu organisieren oder wenn Sie den Zustand zwischen diesen übergeben möchten.

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

Beim Erstellen des Agents können Sie nun alle Methoden der Klasse als Funktionen bereitstellen:

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

Sie können die Funktionen auch mit demselben ai_function Dekorateur wie zuvor dekorieren.

Nächste Schritte

Verwenden von Funktionstools mit Genehmigungen mit menschlicher Beteiligung