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

Waarschuwing

DefaultAzureCredential is handig voor ontwikkeling, maar vereist zorgvuldige overwegingen in de productieomgeving. Overweeg in productie een specifieke referentie te gebruiken (bijvoorbeeld ManagedIdentityCredential) om latentieproblemen, onbedoelde referentieprobing en potentiële beveiligingsrisico's van terugvalmechanismen te voorkomen.

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

Aanbeveling

Zie de .NET-voorbeelden voor volledige runnable voorbeelden.

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

Indien u de name en description parameters niet specificeert in de @tool-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()).as_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()).as_agent(
    instructions="You are a helpful assistant",
    tools=[tools.get_weather, tools.get_weather_details]
)

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

Volledig voorbeeld

# 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())

Volgende stappen

Gebruik van functiehulpmiddelen met menselijke goedkeuring in de controlelus