Řízení dostupnosti nástrojů

Note

Rozhraní API pro postupné zpřístupňování nástrojů (FunctionInvocationContext.add_tools / remove_tools) je v současnosti k dispozici pouze pro Python.

Tato stránka obsahuje tři doplňkové techniky řízení nástrojů, které model může volat a v jakém pořadí, a to vše v rámci jednoho spuštění agenta, aniž by vyžadoval pracovní postup:

• Progresivní expozice nástrojů – přidávání nebo odebírání nástrojů za běhu z nástroje nebo middlewaru funkcí, takže model vidí jenom nástroje, které je připravené použít.
• Řízení volání pomocí middlewaru — použijte middleware funkce k validaci argumentů volání a vrácení opravné zpětné vazby bez spuštění podkladové funkce.
• Vynucené první volání – použijte tool_choice k tomu, aby model vyžadoval volání konkrétního nástroje před ostatními.

Note

Omezení pořadí po dvojicích, například „vždy zavolat get_record před update_record“, nevyžadují pracovní postup. Postupy na této stránce řeší tento vzor v rámci jediného běhu. Workflow jsou určena pro skutečnou vícekrokovou orchestraci napříč běhy nebo paralelními větvemi.

Postupné zpřístupňování nástrojů

Progresivní expozice nástrojů umožňuje spustit běh s malou sadou nástrojů a přidávat nebo odebírat nástroje v reakci na dřívější výsledky nástrojů, a to vše ve stejném spuštění. Model vidí aktualizovanou sadu až v další iteraci smyčky volání funkcí; volání nástrojů, která už byla vyžádána v právě zpracovávané dávce, se ještě provedou, než se změna projeví.

Rozhraní API je experimentální a je dostupné na FunctionInvocationContext:

Člen	Description
ctx.tools	Aktuální, měnitelná list nástrojů pro aktuální běh. None při volání funkce mimo smyčku volání funkcí.
ctx.add_tools(tools)	Přidejte jeden nebo více nástrojů. Volatelné objekty se zapisují jako FunctionTool. Opětovné přidání stejného objektu je no-op; jiný objekt s duplicitním názvem vyvolá ValueError. Všechno, nebo nic: pokud by některý nástroj v dávce vyvolal chybu, nepřidá se žádný.
ctx.remove_tools(tools)	Odeberte pomocí názvu, objektu nástroje nebo volatelného objektu. Názvy, které nejsou v seznamu, se bezobslužně ignorují.

Obě pomocné funkce vysílají ExperimentalWarning při prvním volání v rámci procesu (ID funkce PROGRESSIVE_TOOLS). Volání kterékoli z pomocných funkcí mimo smyčku pro volání funkcí vyvolá RuntimeError.

Important

Seznam nástrojů se obnoví na původní sadu při každém novém agent.run() volání, takže všechna hradla se automaticky přezbrojí pro každé otáčení.

Note

Progresivní expozice nástrojů se vztahuje pouze na standardní smyčku volání funkcí. Není k dispozici pro zprostředkovatele CodeAct (agent-framework-monty, agent-framework-hyperlight), kde model vidí místo jednotlivých schémat nástrojů jednu plochu provádění kódu. Volání add_tools nebo remove_tools z uvnitř sandboxu CodeAct vyvolává RuntimeError. Chcete-li změnit sadu nástrojů pro agenta CodeAct, použijte mezi jednotlivými spuštěními vlastní add_tools / remove_tool / clear_tools metody poskytovatele.

Model zavaděče

Předem zaregistrujte malou sadu nástrojů typu „loader“ a umožněte modelu podle potřeby načítat další nástroje. Počáteční schéma tak zůstane malé, což zlepšuje přesnost výběru nástrojů a snižuje náklady.

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

Úplná spustitelná ukázka je na python/samples/02-agents/tools/dynamic_tool_exposure.pyadrese .

Schéma hradlování

Nejprve zaregistrujte pouze nástroj pro čtení. Nástroj pro čtení přidá nástroj pro zápis po úspěšném načtení, takže model nemůže před spuštěním nástroje pro čtení volat nástroj pro zápis.

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
)

Protože se ctx.tools na začátku každého běhu resetuje na [get_record], brána se pro každý tah konverzace automaticky znovu aktivuje.

Řízení přístupu middlewaru

Middleware funkce může zkontrolovat argumenty čekajícího volání nástroje a odmítnout ho před provedením základní funkce nastavením context.result bez volání call_next(). Řetězec přiřazený context.result k modelu se vrátí jako výsledek funkce a poskytne jí zpětnou zpětnou vazbu.

To je užitečné pro kontroly na úrovni argumentů, které potřebují informace, které nejsou k dispozici v době definice schématu, například ověření, že aktualizace cílí na stejnou položku, která byla načtena dříve v běhu.

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

Přidejte middleware do agenta:

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

Další informace o middlewaru funkcí najdete v tématech Definování middlewaru a Přepsání výsledků.

Vynucení volání nástroje pomocí tool_choice

Chcete-li vynutit, aby model jako první akci zavolal konkrétní nástroj, předejte tool_choice s režimem "required" a required_function_name. Framework po první iteraci automaticky resetuje tool_choice na None, takže je model při dalších iteracích k dispozici.

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

Pole tool_choice přijímá slovník ToolMode nebo zkrácené řetězce "auto", "required" nebo "none":

from agent_framework import ToolMode

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

Sémantika a upozornění

Chování	Detail
Efekt další iterace	add_tools / remove_tools mutace jsou pro model viditelné v další iteraci smyčky. Volání nástrojů, která už byla v aktuální dávce odeslána, se dokončí bez ohledu na to.
Dávka v letu	Pokud model požaduje několik nástrojů v jedné dávce, všechny se spustí před odesláním aktualizovaného seznamu nástrojů zpět.
Duplicitní názvy	Opětovné přidání stejného objektu je no-op. Přidání jiného objektu, jehož název se shoduje s názvem existujícího nástroje, vyvolá ValueError. Celá dávka se ověří před jakýmkoli přidáním, takže duplicitní položka uprostřed seznamu ponechá aktuální seznam beze změny.
Chyba vnější smyčky	Volání add_tools nebo remove_tools když ctx.tools is None vyvolá RuntimeError. K tomu dochází v případě, že je funkce vyvolána přímo (například prostřednictvím FunctionTool.invoke) místo smyčky agenta.
Experimentální stav	Obě pomocné rutiny při prvním volání v rámci každého procesu vrátí ExperimentalWarning. Potlačte pomocí warnings.filterwarnings("ignore", category=FutureWarning), v případě potřeby.
Rozsah jednotlivých spuštění	Aktuální seznam nástrojů je nová kopie vytvořená z normalize_tools na začátku každého volání agent.run(). Původní tools kontejner volajícího není nikdy změněn.
Vyloučení CodeAct	Není k dispozici pro poskytovatele CodeAct agent-framework-monty nebo agent-framework-hyperlight.

Note

Rozhraní API pro dostupnost nástrojů runtime popsaná na této stránce jsou v současnosti dostupná pouze pro Python. Vzory pro nástroje Go najdete v tématech Funkční nástroje a Používání funkčních nástrojů při schvalování se zapojením člověka.

Další kroky

Funkční nástroje

Definování middlewaru