Aracıyla fonksiyon araçlarını kullanma

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

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

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

# 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",
)
def get_weather(location: str, unit: str = "celsius") -> str:
    """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.",
    schema=get_current_time_schema,
    approval_mode="never_require",
)
def get_current_time(timezone: str = "UTC") -> str:
    """Get the current time."""

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

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

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.

# 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"},
        },
        "required": ["reason"],
    },
)

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 .

İşlev araçları

İşlev araçları, aracıların özel Go işlevlerini çağırmasına olanak tanır. Paket, functool otomatik şema oluşturma ile tür açısından güvenli araçları tanımlamanın basit bir yolunu sağlar.

İşlev aracı tanımlama

import (
    "context"

    "github.com/microsoft/agent-framework-go/tool"
    "github.com/microsoft/agent-framework-go/tool/functool"
)

var weatherTool = functool.MustNew(functool.Config{
    Name:        "weather",
    Description: "Get the current weather for a given location",
}, func(_ context.Context, location string) (string, error) {
    return fmt.Sprintf("The weather in %s is cloudy with a high of 15°C.", location), nil
})

İşlev imzası aracın giriş şemasını belirler. context.Context parametresi çerçeve tarafından eklenir ve modele gösterilmez.

Yapılandırılmış giriş türleri

Birden çok parametresi olan araçlar için bir yapı tanımlayın:

type WeatherInput struct {
    Location string `json:"location" jsonschema:"description=The city to check weather for"`
    Unit     string `json:"unit" jsonschema:"description=Temperature unit (celsius or fahrenheit),enum=celsius,enum=fahrenheit"`
}

var weatherTool = functool.MustNew(functool.Config{
    Name:        "weather",
    Description: "Get weather for a location",
}, func(_ context.Context, input WeatherInput) (string, error) {
    return fmt.Sprintf("Weather in %s: 15°%s", input.Location, input.Unit), nil
})

Araçlarla bir ajan oluşturun

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Instructions: "You are a helpful assistant.",
    Config: agent.Config{
        Tools: []tool.Tool{weatherTool},
    },
})

resp, err := a.RunText(ctx, "What is the weather like in Amsterdam?").Collect()

Bir ajanı işlev aracı olarak kullan

Herhangi bir ajan, başka bir ajan tarafından kullanılmak üzere bir fonksiyon aracı olarak sarmalanabilir:

import "github.com/microsoft/agent-framework-go/tool/agenttool"

weatherAgent := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Instructions: "You answer questions about the weather.",
    Config: agent.Config{
        Name:        "WeatherAgent",
        Description: "An agent that answers weather questions.",
        Tools:       []tool.Tool{weatherTool},
    },
})

mainAgent := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Instructions: "You are a helpful assistant who responds in French.",
    Config: agent.Config{
        Tools: []tool.Tool{agenttool.New(weatherAgent, agenttool.Config{})},
    },
})

Yerel kabuk aracını kullan

Go SDK'sı, yerel kabuk yürütme için tool/shelltool içerir. Araç varsayılan olarak onay gerektirir ve modelin geçerli kabuk ailesini, çalışma dizinini ve ortak araç sürümlerini bilmesi için bir ortam bağlam sağlayıcısıyla eşleştirilebilir.

import "github.com/microsoft/agent-framework-go/tool/shelltool"

shell, err := shelltool.NewLocal(shelltool.LocalConfig{
    Mode: shelltool.ModeStateless,
})
if err != nil {
    return err
}
defer shell.Close()

envProvider := shelltool.NewEnvironmentProvider(shell, shelltool.EnvironmentProviderConfig{})

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Instructions: "Run shell commands only when needed and summarize the result.",
    Config: agent.Config{
        Tools:            []tool.Tool{shell},
        ContextProviders: []agent.ContextProvider{envProvider},
    },
})

Her çağrının yeni bir kabukta çalıştırılması gerektiğinde kullanın shelltool.ModeStateless . shelltool.ModePersistent öğesini yalnızca, değiştirilen dizinler veya dışa aktarılan ortam değişkenleri gibi kabuk durumunun tek bir aracı oturumunda çağrılar arasında korunması gerekiyorsa kullanın. Yalnızca bağımsız bir yalıtım sınırı sağladığınızda ve yerleşik onay kapısına ihtiyacınız olmadığında ayarlayın AcknowledgeUnsafe: true .

Çalışma zamanında araç kullanılabilirliğini denetleme

Bir ajan çalışması sırasında FunctionInvocationContext.add_tools() / remove_tools() kullanarak araç ekleyebilir veya kaldırabilir, çağrıları işlev ara yazılımı ile denetleyebilir ya da tool_choice ile belirli bir ilk çağrıyı zorunlu kılabilirsiniz. Desenlerin tamamı için bkz. Araç kullanılabilirliğini denetleme.