Aracıyla fonksiyon araçlarını kullanma

Bu öğretici adım, Azure OpenAI Sohbet Tamamlama hizmetine dayalı olarak oluşturulmuş bir ajanın işlev araçlarıyla nasıl kullanılacağını gösterir.

Önemli

Tüm aracı türleri işlev araçlarını desteklemez. Bazıları, çağıranın kendi işlevlerini sağlamasına izin vermeden yalnızca özel yerleşik araçları destekleyebilir. Bu adımda işlev araçlarını destekleyen bir ChatClientAgentkullanılır.

Önkoşullar

Önkoşullar ve NuGet paketlerini yükleme için bu öğreticideki Basit bir aracı oluşturma ve çalıştırma adımına bakın.

İşlev araçlarıyla aracı oluşturma

İşlev araçları yalnızca aracının gerektiğinde çağırabilmesini istediğiniz özel kodlardır. AIFunctionFactory.Create yöntemini kullanarak herhangi bir C# yöntemini işlev AIFunction aracı haline getirebilirsiniz, bu yöntemden bir örnek oluşturarak.

Farklı işlevler arasında daha doğru seçim yapmak için işlev veya parametreleri hakkında aracıya ek açıklamalar sağlamanız gerekiyorsa, yönteminde ve parametrelerinde özniteliğini kullanabilirsiniz System.ComponentModel.DescriptionAttribute .

Burada, belirli bir konumun hava durumunu alma sahtesini gösteren basit bir işlev aracı örneği verilmiştir. Kendisi ve konum parametresi hakkında aracıya ek açıklamalar sağlamak için açıklama öznitelikleriyle donatılmıştır.

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

Aracıyı oluştururken, AsAIAgent yöntemine bir araç listesi geçirerek aracıya işlev aracını artık sağlayabilirsiniz.

using System;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
     .AsAIAgent(
        model: "gpt-4o-mini",
        instructions: "You are a helpful assistant",
        tools: [AIFunctionFactory.Create(GetWeather)]);

Uyarı

DefaultAzureCredential geliştirme için uygundur ancak üretimde dikkatli bir şekilde dikkate alınması gerekir. Üretimde gecikme sorunları, istenmeyen kimlik bilgisi yoklama ve geri dönüş mekanizmalarından kaynaklanan olası güvenlik risklerini önlemek için belirli bir kimlik bilgisi (ör ManagedIdentityCredential. ) kullanmayı göz önünde bulundurun.

Artık ajanı her zamanki gibi çalıştırabilirsiniz ve ajan gerektiğinde işlev aracını GetWeather çağırabilir.

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

Tip

Çalıştırılabilir örneklerin tamamı için .NET örneklerine bakın.

Önemli

Tüm aracı türleri işlev araçlarını desteklemez. Bazıları, çağıranın kendi işlevlerini sağlamasına izin vermeden yalnızca özel yerleşik araçları destekleyebilir. Bu adım, işlev araçlarını destekleyen sohbet istemcileri aracılığıyla oluşturulan aracıları kullanır.

Önkoşullar

Önkoşullar ve Python paketlerini yükleme için bu öğreticideki Basit bir aracı oluşturma ve çalıştırma adımına bakın.

İşlev araçlarıyla aracı oluşturma

İşlev araçları yalnızca aracının gerektiğinde çağırabilmesini istediğiniz özel kodlardır. Herhangi bir Python işlevini aracıyı oluştururken aracının tools parametresine geçirerek işlev aracısına dönüştürebilirsiniz.

Farklı işlevler arasında daha doğru seçim yapmak için işlev veya parametreleri hakkında aracıya ek açıklamalar sağlamanız gerekiyorsa, açıklama sağlamak için Python'ın tür ek açıklamalarını ve Pydantic'in Annotated açıklamalarını Field kullanabilirsiniz.

Burada, belirli bir konumun hava durumunu alma sahtesini gösteren basit bir işlev aracı örneği verilmiştir. Tür tanımlamalarını, aracıya işlev ve konum parametresi hakkında ek açıklamalar sağlamak için kullanır.

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

Ayrıca, işlevin @tool adını ve açıklamasını açıkça belirtmek için dekoratör de kullanabilirsiniz:

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

Dekoratörde namedescription ve @tool parametrelerini belirtmezseniz, çerçeve otomatik olarak işlevin adını ve docstring'i geri dönüş olarak kullanır.

@tool ile tanımlı şemaları kullanın

Modele sunulan şema üzerinde tam denetime ihtiyacınız olduğunda parametresini schema öğesine @toolgeçirin. Pydantic modeli veya ham JSON şema sözlüğü sağlayabilirsiniz.

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

Bir araç için yalnızca çalışma zamanı bağlamı aktarın

Modelin sağlaması gereken değerler için normal işlev parametrelerini kullanın. Çalışma zamanı değerleri için, FunctionInvocationContext veya geçerli oturum gibi sadece function_invocation_kwargs kullanın. Eklenen bağlam parametresi, modele sunulan şemadan gizlenir.

import asyncio
from typing import Annotated

from agent_framework import Agent, FunctionInvocationContext, tool
from agent_framework.openai import OpenAIChatClient
from dotenv import load_dotenv
from pydantic import Field
# Define the function tool with explicit invocation context.
# The context parameter can also be declared as an untyped ``ctx`` parameter.
@tool(approval_mode="never_require")
def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
    ctx: FunctionInvocationContext,
) -> str:
    """Get the weather for a given location."""
    # Extract the injected argument from the explicit context
    user_id = ctx.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 = Agent(
        client=OpenAIChatClient(),
        name="WeatherAgent",
        instructions="You are a helpful weather assistant.",
        tools=[get_weather],
    )

    # Pass the runtime context explicitly when running the agent.
    response = await agent.run(
        "What is the weather like in Amsterdam?",
        function_invocation_kwargs={"user_id": "user_123"},

ctx.kwargs, ctx.session ve orta katman yazılımı hakkında daha fazla ayrıntı için, bkz: Çalışma Zamanı Bağlamı.

Yalnızca bildirim için araçlar oluşturma

Çerçeve dışında bir araç uygulandıysa (örneğin, kullanıcı arabiriminde istemci tarafı), bunu, bir uygulama olmadan FunctionTool(..., func=None) kullanarak bildirebilirsiniz. Model yine de aracı hakkında düşünebilir ve çağırabilir, uygulamanız ise sonucu daha sonra sağlayabilir.

# 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"},

Aracıyı oluştururken işlev aracını tools parametresine geçirerek artık aracıya sağlayabilirsiniz.

import asyncio
import os
from agent_framework.openai import OpenAIChatCompletionClient
from azure.identity import AzureCliCredential

agent = OpenAIChatCompletionClient(
    model=os.environ["AZURE_OPENAI_CHAT_COMPLETION_MODEL"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    credential=AzureCliCredential(),
).as_agent(
    instructions="You are a helpful assistant",
    tools=get_weather
)

Artık ajanı her zamanki gibi çalıştırabilirsiniz ve ajan gerektiğinde işlev aracını get_weather çağırabilir.

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

asyncio.run(main())

Birden çok işlev aracıyla sınıf oluşturma

Çeşitli araçlar bağımlılıkları veya değişebilir durumu paylaştığında, bunları bir sınıfa sarmalayıp bağlı yöntemleri aracıya geçirin. Hizmet istemcileri, özellik bayrakları veya önbelleğe alınmış durum gibi modelin sağlamaması gereken değerler için sınıf özniteliklerini kullanın.

import asyncio
from typing import Annotated

from agent_framework import Agent, tool
from agent_framework.openai import OpenAIChatClient
from dotenv import load_dotenv
class MyFunctionClass:
    def __init__(self, safe: bool = False) -> None:
        """Simple class with two tools: divide and add.

        The safe parameter controls whether divide raises on division by zero or returns `infinity` for divide by zero.
        """
        self.safe = safe

    def divide(
        self,
        a: Annotated[int, "Numerator"],
        b: Annotated[int, "Denominator"],
    ) -> str:
        """Divide two numbers, safe to use also with 0 as denominator."""
        result = "∞" if b == 0 and self.safe else a / b
        return f"{a} / {b} = {result}"

    def add(
        self,
        x: Annotated[int, "First number"],
        y: Annotated[int, "Second number"],
    ) -> str:
        return f"{x} + {y} = {x + y}"


async def main():
    # Creating my function class with safe division enabled
    tools = MyFunctionClass(safe=True)
    # Applying the tool decorator to one of the methods of the class
    add_function = tool(description="Add two numbers.")(tools.add)

    agent = Agent(
        client=OpenAIChatClient(),
        name="ToolAgent",
        instructions="Use the provided tools.",
    )
    print("=" * 60)
    print("Step 1: Call divide(10, 0) - tool returns infinity")
    query = "Divide 10 by 0"
    response = await agent.run(
        query,
        tools=[add_function, tools.divide],
    )
    print(f"Response: {response.text}")
    print("=" * 60)
    print("Step 2: Call set safe to False and call again")
    # Disabling safe mode to allow exceptions
    tools.safe = False

Bu desen, uzun ömürlü araç durumu için uygundur. Bunun yerine, çağrı başına değer değiştiğinde kullanın FunctionInvocationContext .

Sonraki Adımlar

İnsan onayı sürecine sahip fonksiyonel araçların kullanımı