Partager via

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 AsAIAgent 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 DefaultAzureCredential())
     .GetChatClient("gpt-4o-mini")
     .AsAIAgent(instructions: "You are a helpful assistant", tools: [AIFunctionFactory.Create(GetWeather)]);

Avertissement

DefaultAzureCredential est pratique pour le développement, mais nécessite une considération minutieuse en production. En production, envisagez d’utiliser des informations d’identification spécifiques (par exemple ManagedIdentityCredential) pour éviter les problèmes de latence, la détection involontaire des informations d’identification et les risques de sécurité potentiels liés aux mécanismes de secours.

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?"));

Conseil / Astuce

Consultez les exemples .NET pour obtenir des exemples exécutables complets.

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 @tool 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 tool

@tool(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 @tool, 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()).as_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 la fonction get_weather si besoin.

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()).as_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 @tool décorateur que précédemment.

Exemple complet

# Copyright (c) Microsoft. All rights reserved.

import asyncio
from typing import Annotated, Any

from agent_framework import tool
from agent_framework.openai import OpenAIResponsesClient
from pydantic import Field

"""
AI Function with kwargs Example

This example demonstrates how to inject custom keyword arguments (kwargs) into an AI function
from the agent's run method, without exposing them to the AI model.

This is useful for passing runtime information like access tokens, user IDs, or
request-specific context that the tool needs but the model shouldn't know about
or provide.
"""


# Define the function tool with **kwargs to accept injected arguments
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
    **kwargs: Any,
) -> str:
    """Get the weather for a given location."""
    # Extract the injected argument from kwargs
    user_id = kwargs.get("user_id", "unknown")

    # Simulate using the user_id for logging or personalization
    print(f"Getting weather for user: {user_id}")

    return f"The weather in {location} is cloudy with a high of 15°C."


async def main() -> None:
    agent = OpenAIResponsesClient().as_agent(
        name="WeatherAgent",
        instructions="You are a helpful weather assistant.",
        tools=[get_weather],
    )

    # Pass the injected argument when running the agent
    # The 'user_id' kwarg will be passed down to the tool execution via **kwargs
    response = await agent.run("What is the weather like in Amsterdam?", user_id="user_123")

    print(f"Agent: {response.text}")


if __name__ == "__main__":
    asyncio.run(main())

# Copyright (c) Microsoft. All rights reserved.

import asyncio
from typing import Annotated, Any

from agent_framework import tool
from agent_framework.openai import OpenAIResponsesClient
from pydantic import Field

"""
AI Function with kwargs Example

This example demonstrates how to inject custom keyword arguments (kwargs) into an AI function
from the agent's run method, without exposing them to the AI model.

This is useful for passing runtime information like access tokens, user IDs, or
request-specific context that the tool needs but the model shouldn't know about
or provide.
"""


# Define the function tool with **kwargs to accept injected arguments
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
    **kwargs: Any,
) -> str:
    """Get the weather for a given location."""
    # Extract the injected argument from kwargs
    user_id = kwargs.get("user_id", "unknown")

    # Simulate using the user_id for logging or personalization
    print(f"Getting weather for user: {user_id}")

    return f"The weather in {location} is cloudy with a high of 15°C."


async def main() -> None:
    agent = OpenAIResponsesClient().as_agent(
        name="WeatherAgent",
        instructions="You are a helpful weather assistant.",
        tools=[get_weather],
    )

    # Pass the injected argument when running the agent
    # The 'user_id' kwarg will be passed down to the tool execution via **kwargs
    response = await agent.run("What is the weather like in Amsterdam?", user_id="user_123")

    print(f"Agent: {response.text}")


if __name__ == "__main__":
    asyncio.run(main())

Prochaines étapes

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

  • Last updated on