Not
Åtkomst till denna sida kräver auktorisation. Du kan prova att logga in eller byta katalog.
Åtkomst till denna sida kräver auktorisation. Du kan prova att byta katalog.
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 AsAIAgent 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 DefaultAzureCredential())
.GetChatClient("gpt-4o-mini")
.AsAIAgent(instructions: "You are a helpful assistant", tools: [AIFunctionFactory.Create(GetWeather)]);
Varning
DefaultAzureCredential är praktiskt för utveckling men kräver noggrant övervägande i produktion. I produktion bör du överväga att använda en specifik autentiseringsuppgift (t.ex. ManagedIdentityCredential) för att undvika problem med svarstid, oavsiktlig avsökning av autentiseringsuppgifter och potentiella säkerhetsrisker från reservmekanismer.
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?"));
Tips/Råd
Se .NET-exemplen för fullständiga körbara exempel.
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 @tool för att uttryckligen ange funktionens namn och beskrivning:
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."
Om du inte anger parametrarna name och description i dekoratören @tool använder ramverket automatiskt funktionens namn och dokumentsträng som återställningar.
Använda explicita scheman med @tool
När du behöver fullständig kontroll över det schema som exponeras för modellen skickar du parametern schema till @tool.
Du kan ange antingen en pydantisk modell eller en rå JSON-schemaordlista.
# Load environment variables from .env file
load_dotenv()
# Approach 1: Pydantic model as explicit schema
class WeatherInput(BaseModel):
"""Input schema for the weather tool."""
location: Annotated[str, Field(description="The city name to get weather for")]
unit: Annotated[str, Field(description="Temperature unit: celsius or fahrenheit")] = "celsius"
@tool(
name="get_weather",
description="Get the current weather for a given location.",
schema=WeatherInput,
approval_mode="never_require",
"""Get the current weather for a location."""
return f"The weather in {location} is 22 degrees {unit}."
# Approach 2: JSON schema dictionary as explicit schema
get_current_time_schema = {
"type": "object",
"properties": {
"timezone": {"type": "string", "description": "The timezone to get the current time for", "default": "UTC"},
},
}
@tool(
name="get_current_time",
description="Get the current time in a given timezone.",
Skapa endast deklarationsverktyg
Om ett verktyg implementeras utanför ramverket (till exempel klientsidan i ett användargränssnitt) kan du deklarera det utan en implementering med .FunctionTool(..., func=None)
Modellen kan fortfarande resonera om och anropa verktyget, och ditt program kan ge resultatet senare.
# Load environment variables from .env file
load_dotenv()
# A declaration-only tool: the schema is sent to the LLM, but the framework
# has no implementation to execute. The caller must supply the result.
get_user_location = FunctionTool(
name="get_user_location",
func=None,
description="Get the user's current city. Only the client application can resolve this.",
input_model={
"type": "object",
"properties": {
"reason": {"type": "string", "description": "Why the location is needed"},
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()).as_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()).as_agent(
instructions="You are a helpful assistant",
tools=[tools.get_weather, tools.get_weather_details]
)
Du kan också dekorera funktionerna med samma @tool dekoratör som tidigare.
Fullständigt exempel
# 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())