Utilisation d’outils de fonction avec un agent

Cette étape du tutoriel vous montre comment utiliser des outils de fonction avec un agent, où l’agent est basé sur le service Azure OpenAI Chat Completion.

Important

Tous les types d’agents ne prennent pas en charge les outils de fonction. Certains peuvent uniquement prendre en charge les outils intégrés personnalisés, sans permettre à l’appelant de fournir leurs propres fonctions. Cette étape utilise un ChatClientAgent, qui prend en charge les outils de fonction.

Prerequisites

Pour connaître les prérequis et l’installation des packages NuGet, consultez l’étape Créer et exécuter un agent simple dans ce tutoriel.

Créer l’agent avec des outils de fonction

Les outils de fonction sont simplement du code personnalisé que vous souhaitez que l’agent puisse appeler si nécessaire. Vous pouvez transformer n’importe quelle méthode C# en outil de fonction à l’aide de la AIFunctionFactory.Create méthode pour créer une AIFunction instance à partir de la méthode.

Si vous devez fournir des descriptions supplémentaires sur la fonction ou ses paramètres à l’agent, afin qu’il puisse choisir plus précisément entre différentes fonctions, vous pouvez utiliser l’attribut System.ComponentModel.DescriptionAttribute sur la méthode et ses paramètres.

Voici un exemple d’outil de fonction simple qui simule l'obtention de la météo pour un emplacement donné. Il est décoré avec des attributs de description pour fournir des descriptions supplémentaires sur lui-même et son paramètre d’emplacement à l’agent.

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

Lors de la création de l’agent, vous pouvez maintenant fournir l’outil de fonction à l’agent en passant une liste d’outils à la CreateAIAgent méthode.

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

Maintenant, vous pouvez simplement exécuter l'agent comme d'habitude, et l'agent sera en mesure d'appeler la fonction GetWeather si besoin.

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

Important

Tous les types d’agents ne prennent pas en charge les outils de fonction. Certains peuvent uniquement prendre en charge les outils intégrés personnalisés, sans permettre à l’appelant de fournir leurs propres fonctions. Cette étape utilise des agents créés via des clients de messagerie instantanée, qui prennent en charge les outils fonctionnels.

Prerequisites

Pour connaître les prérequis et l’installation des packages Python, consultez l’étape Créer et exécuter un agent simple dans ce tutoriel.

Créer l’agent avec des outils de fonction

Les outils de fonction sont simplement du code personnalisé que vous souhaitez que l’agent puisse appeler si nécessaire. Vous pouvez transformer n’importe quelle fonction Python en fonction outil en la transmettant au paramètre tools lors de la création de l’agent.

Si vous devez fournir des descriptions supplémentaires sur la fonction ou ses paramètres à l’agent, afin qu’il puisse choisir plus précisément entre différentes fonctions, vous pouvez utiliser les annotations de type Python avec Annotated et Pydantic Field pour fournir des descriptions.

Voici un exemple d’outil de fonction simple qui simule l'obtention de la météo pour un emplacement donné. Il utilise des annotations de type pour fournir des descriptions supplémentaires sur la fonction et son paramètre d’emplacement à l’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."

Vous pouvez également utiliser le ai_function décorateur pour spécifier explicitement le nom et la description de la fonction :

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

Si vous ne spécifiez pas les paramètres name et description dans le décorateur ai_function, le framework utilisera automatiquement le nom et le docstring de la fonction en tant que secours.

Lors de la création de l’agent, vous pouvez maintenant fournir l’outil de fonction à l’agent en le transmettant au tools paramètre.

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
)

Maintenant, vous pouvez simplement exécuter l’agent comme d'habitude, et l’agent sera en mesure d’appeler l’outil de fonction get_weather si nécessaire.

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

asyncio.run(main())

Créer une classe avec plusieurs outils de fonction

Vous pouvez également créer une classe qui contient plusieurs outils de fonction en tant que méthodes. Cela peut être utile pour organiser des fonctions associées ensemble ou lorsque vous souhaitez transmettre l'état entre celles-ci.

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

Lors de la création de l’agent, vous pouvez maintenant fournir toutes les méthodes de la classe en tant que fonctions :

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

Vous pouvez également décorer les fonctions avec le même ai_function décorateur que précédemment.

Étapes suivantes

Utilisation d’outils fonctionnels avec intervention humaine dans les approbations en boucle