Araç kullanılabilirliğini denetleme

Uyarı

Aşamalı araç kullanıma sunma API'si (FunctionInvocationContext.add_tools / remove_tools) şu anda yalnızca Python'da kullanılabilir.

Bu sayfa, bir modelin hangi araçları çağırabileceğini ve hangi sırada çağırabileceğini denetlemek için iş akışı gerektirmeden tek bir aracı çalıştırması için üç tamamlayıcı tekniği kapsar:

• Araçların aşamalı olarak gösterilmesi — çalışma zamanında, bir araçtan veya işlev ara katmanı içinden araçlar ekleyin ya da kaldırın; böylece model yalnızca kullanmaya hazır olduğu araçları görür.
• Ara katman geçidi — işlev çağrısı argümanlarını doğrulamak ve altta yatan işlevi yürütmeden düzeltici geri bildirim sağlamak için işlev ara katmanını kullanın.
• Zorlamalı ilk çağrı — modelin diğerlerinden önce belirli bir aracı çağırmasını istemek için kullanın tool_choice .

Uyarı

"Always call get_record before update_record" gibi çift tabanlı sıralama kısıtlamaları bir iş akışı gerektirmez. Bu sayfadaki teknikler, bu deseni tek bir çalıştırma sırasında ele alır. İş akışları, çalıştırmalar ya da paralel dallar arasında gerçek çok adımlı orkestrasyon için kullanılır.

Araçların kademeli olarak sunulması

Aşamalı araç pozlaması, küçük bir araç kümesiyle bir çalıştırma başlatmanıza ve önceki araç sonuçlarına yanıt olarak aynı çalıştırmada araçlar eklemenize veya kaldırmanıza olanak tanır. Model, güncellenmiş kümeyi yalnızca fonksiyon çağırma döngüsünün bir sonraki yinelemesinde görür; devam eden toplu işlemde zaten istenmiş olan araç çağrıları, değişiklik etkisini göstermeden önce yine çalıştırılır.

API deneyseldir ve üzerinde FunctionInvocationContextyaşar:

Üye	Açıklama
ctx.tools	Geçerli çalıştırma için canlı, değiştirilebilir list araçlar. None işlevi bir işlev çağırma döngüsü dışında çağrıldığında.
ctx.add_tools(tools)	Bir veya daha fazla araç ekleyin. Çağrılabilen öğeler olarak FunctionToolsarmalanmıştır. Aynı nesneyi yeniden eklemek hiçbir işlem yapmaz; aynı ada sahip farklı bir nesne ValueError hatası verir. Tümü veya hiç: Toplu işteki herhangi bir araç yükseltilirse hiçbiri eklenmez.
ctx.remove_tools(tools)	Ada, araç nesnesine veya çağrılabilir nesneye göre kaldırın. Listede bulunmayan adlar sessizce göz ardı edilir.

Her iki yardımcı da, bir işlem içinde ilk kez çağrıldıklarında ExperimentalWarning çıktısı verir (özellik kimliği PROGRESSIVE_TOOLS). İşlev çağırma döngüsünün dışında iki yardımcıdan herhangi birini çağırmak RuntimeError hatasına neden olur.

Important

Araç listesi, her yeni agent.run() çağrısında başlangıçtaki listeye sıfırlanır; böylece tüm geçitler her turda otomatik olarak yeniden etkinleştirilir.

Uyarı

Araçların aşamalı olarak sunulması yalnızca standart fonksiyon çağırma döngüsü için geçerlidir. Bu, modelin ayrı ayrı araç şemaları yerine tek bir kod yürütme yüzeyi gördüğü CodeAct sağlayıcılarında (agent-framework-monty, agent-framework-hyperlight) kullanılamaz. CodeAct korumalı alanı içinden add_tools veya remove_tools çağrılması, RuntimeError hatasına neden olur. CodeAct aracısının araç kümesini değiştirmek için, çalıştırmalar arasında sağlayıcının kendi add_tools / remove_tool / clear_tools yöntemlerini kullanın.

Yükleyici-aracı deseni

Başta küçük bir “yükleyici” araç kümesi kaydedin ve modelin gerektiğinde ek araçları çağırmasına izin verin. Bu, ilk şemayı küçük tutarak araç seçimi doğruluğunu artırır ve maliyeti azaltır.

import asyncio
import warnings
from typing import Annotated

from agent_framework import Agent, FunctionInvocationContext, tool
from agent_framework.openai import OpenAIChatClient
from pydantic import Field

warnings.filterwarnings("ignore", category=FutureWarning)  # suppress ExperimentalWarning for brevity


@tool(approval_mode="never_require")
def factorial(n: Annotated[int, Field(description="A non-negative integer.")]) -> str:
    """Compute the factorial of n."""
    if n < 0:
        return "Error: n must be a non-negative integer."
    result = 1
    for value in range(2, n + 1):
        result *= value
    return f"{n}! = {result}"


@tool(approval_mode="never_require")
def fibonacci(n: Annotated[int, Field(description="The 0-based index in the Fibonacci sequence.")]) -> str:
    """Compute the n-th Fibonacci number."""
    if n < 0:
        return "Error: n must be a non-negative integer."
    a, b = 0, 1
    for _ in range(n):
        a, b = b, a + b
    return f"fib({n}) = {a}"


# The ctx parameter is injected by the framework and is NOT visible to the model.
@tool(approval_mode="never_require")
def load_math_tools(ctx: FunctionInvocationContext) -> str:
    """Load additional math tools (factorial, fibonacci) so they can be used."""
    ctx.add_tools([factorial, fibonacci])
    return "Loaded math tools: factorial, fibonacci. You can now call them."


async def main() -> None:
    agent = Agent(
        client=OpenAIChatClient(),
        name="MathAgent",
        instructions=(
            "You are a math assistant. "
            "If you need math capabilities that are not yet available, call load_math_tools first."
        ),
        tools=[load_math_tools],  # agent starts with only the loader
    )
    print(await agent.run("What is 5 factorial?"))


asyncio.run(main())

Tam çalıştırılabilir örnek python/samples/02-agents/tools/dynamic_tool_exposure.py konumunda bulunabilir.

Geçitleme örüntüsü

Başlangıçta yalnızca okuma aracını kaydedin. Okuma aracı, başarılı bir getirmeden sonra yazma aracını ekler, bu nedenle okuma aracı çalışmadan önce model yazma aracını çağıramaz.

from agent_framework import Agent, FunctionInvocationContext, tool
from agent_framework.openai import OpenAIChatClient

_last_fetched_id: str | None = None


@tool(approval_mode="never_require")
def get_record(record_id: str, ctx: FunctionInvocationContext) -> str:
    """Fetch a record. Unlocks update_record for the same record."""
    global _last_fetched_id
    _last_fetched_id = record_id
    ctx.add_tools(update_record)  # gate: expose the write tool now
    return f"Record {record_id}: title='Example record', status='open'"


@tool(approval_mode="never_require")
def update_record(record_id: str, status: str) -> str:
    """Update the status of a record."""
    return f"Updated record {record_id} to status '{status}'."


agent = Agent(
    client=OpenAIChatClient(),
    name="RecordAgent",
    instructions="You help manage records. Fetch a record before updating it.",
    tools=[get_record],  # update_record is hidden until get_record runs
)

ctx.tools her çalıştırmanın başında [get_record] olarak sıfırlandığından, kapı her konuşma sırası için otomatik olarak yeniden etkinleşir.

Ara yazılım denetimi

İşlev ara katmanı, bekleyen bir araç çağrısının argümanlarını inceleyebilir ve context.result çağırmadan call_next() ayarlayarak, altta yatan işlev yürütülmeden önce bu çağrıyı reddedebilir. context.result öğesine atanan dize, fonksiyon sonucu olarak modele döndürülür ve böylece modele düzeltici geri bildirim sağlanır.

Bu, örneğin bir güncellemenin çalıştırma sırasında daha önce getirilen aynı öğeyi hedeflediğini doğrulamak gibi, şema tanımlama sırasında mevcut olmayan bilgilere ihtiyaç duyan argüman düzeyindeki kontroller için kullanışlıdır.

from collections.abc import Awaitable, Callable

from agent_framework import FunctionInvocationContext

_last_fetched_id: str | None = None


async def enforce_read_before_write(
    context: FunctionInvocationContext,
    call_next: Callable[[], Awaitable[None]],
) -> None:
    """Reject update_record calls that target a different record than the one fetched."""
    if context.function.name == "update_record":
        requested_id = context.arguments.get("record_id") if hasattr(context.arguments, "get") else None
        if requested_id != _last_fetched_id:
            # Set result without calling call_next — the function never executes.
            context.result = (
                f"Error: you must fetch record '{requested_id}' before updating it. "
                f"Last fetched record was '{_last_fetched_id}'."
            )
            return
    await call_next()

Ara yazılımı aracıya ekleyin:

agent = Agent(
    client=OpenAIChatClient(),
    name="RecordAgent",
    instructions="Fetch a record before updating it.",
    tools=[get_record, update_record],
    middleware=[enforce_read_before_write],
)

İşlev ara yazılımı hakkında daha fazla bilgi için bkz. Ara Yazılım ve Sonuç Geçersiz Kılmalarını Tanımlama.

Bir araç çağrısını tool_choice ile zorlama

Modelin ilk işlem olarak belirli bir aracı çağırmasını gerektirmek için, tool_choice öğesini "required" modu ve bir required_function_name ile iletin. Çerçeve ilk yinelemeden sonra otomatik olarak sıfırlanır tool_choiceNone , böylece model sonraki yinelemelerde serbesttir.

result = await agent.run(
    "Update record REC-42 to status 'in-progress'.",
    options={"tool_choice": {"mode": "required", "required_function_name": "get_record"}},
)

tool_choice alanı, bir ToolMode sözlüğünü veya kısaltılmış "auto", "required" ya da "none" dizelerini kabul eder:

from agent_framework import ToolMode

tool_choice: ToolMode = {"mode": "required", "required_function_name": "get_record"}

Semantik ve uyarılar

Davranış	Ayrıntı
Sonraki yineleme efekti	add_tools / remove_tools mutasyonları bir sonraki döngü yinelemesinde model tarafından görülebilir. Mevcut toplu işlemde zaten gönderilmiş olan araç çağrıları yine de tamamlanır.
Uçuş içi toplu iş	Model tek bir toplu işte birden fazla araç isterse, güncelleştirilmiş araç listesi geri gönderilmeden önce tümü yürütülür.
Yinelenen adlar	Tam olarak aynı nesneyi yeniden eklemek bir no-op. Adı mevcut bir araçla eşleşen farklı bir nesnenin eklenmesi, ValueError hatasına yol açar. Toplu işlemin tamamı herhangi bir ekleme yapılmadan önce doğrulanır; bu nedenle listenin ortasında yinelenen bir öğe bulunması canlı listeyi değiştirmez.
Döngü dışı hata	add_tools, remove_tools oluşturduğunda ctx.tools is None veya RuntimeError çağrısı. Bu durum, işlev aracı döngüsü yerine doğrudan (örneğin aracılığıyla FunctionTool.invoke) çağrıldığında gerçekleşir.
Deneysel durum	Her iki yardımcı da her işlemdeki ilk çağrıda ExperimentalWarning üretir. İstenirse warnings.filterwarnings("ignore", category=FutureWarning) ile gizleyin.
Çalıştırma başına kapsam	Canlı araç listesi, her normalize_tools çağrısının başında agent.run() öğesinden oluşturulan güncel bir kopyadır. Çağıranın orijinal tools kapsayıcısı hiçbir zaman değiştirilmez.
CodeAct dışlama	agent-framework-monty veya agent-framework-hyperlight CodeAct sağlayıcıları için kullanılamaz.

Uyarı

Bu sayfada ele alınan çalışma zamanı aracı kullanılabilirliği API'leri şu anda yalnızca Python için kullanılabilir. Go araç kalıpları için bkz. Fonksiyon Araçları ve insan denetimli onaylarla fonksiyon araçlarını kullanma.

Sonraki Adımlar

İşlev Araçları

Ara Yazılımı Tanımlama