Kontext modulu runtime

Kontext modulu runtime poskytuje middleware s přístupem k informacím o aktuálním spouštěcím prostředí a požadavku. To umožňuje vzory, jako je konfigurace relace, chování specifické pro uživatele a dynamické chování middlewaru na základě podmínek za běhu.

V jazyce C# se kontext modulu runtime obvykle předává prostřednictvím AgentRunOptions nebo vlastního stavu relace. Middleware má přístup k vlastnostem relace a možnostem spuštění, aby mohl provádět rozhodnutí za běhu.

Návod

Informace o tom, jak rozsah middlewaru ovlivňuje přístup k kontextu modulu runtime, najdete na stránce Agent vs. Spustit obor .

Kontext modulu runtime Pythonu je rozdělený mezi tři veřejné plochy:

• session= pro stav konverzace a historii.
• function_invocation_kwargs= pro hodnoty, které by měly vidět pouze nástroje nebo middleware funkcí.
• client_kwargs= pro konfiguraci middlewaru specifického pro chat klienta nebo klienta.

Použijte nejmenší povrch, který odpovídá datům. Díky tomu jsou vstupy nástrojů explicitní a zabraňuje úniku metadat pouze klienta do provádění nástrojů.

Návod

Považovat function_invocation_kwargs za náhradu za starý vzor předávání libovolných veřejných **kwargs nebo agent.run()get_response().

Volba správného kontejneru modulu runtime

Případ použití	Plocha rozhraní API	Přístup z
Sdílení stavu konverzace, ID relací služby nebo historie	session=	ctx.session, AgentContext.session
Předání hodnot modulu runtime pouze nástrojům nebo middlewaru funkcí	function_invocation_kwargs=	FunctionInvocationContext.kwargs
Předání hodnot modulu runtime specifických pro klienta nebo konfigurace middlewaru klienta	client_kwargs=	vlastní get_response(..., client_kwargs=...) implementace

Předání hodnot modulu runtime jen pro nástroj

from typing import Annotated

from agent_framework import FunctionInvocationContext, tool
from agent_framework.openai import OpenAIResponsesClient


@tool(approval_mode="never_require")
def send_email(
    address: Annotated[str, "Recipient email address."],
    ctx: FunctionInvocationContext,
) -> str:
    user_id = ctx.kwargs["user_id"]
    tenant = ctx.kwargs.get("tenant", "default")
    return f"Queued email for {address} from {user_id} ({tenant})"


agent = OpenAIResponsesClient().as_agent(
    name="Notifier",
    instructions="Send email updates.",
    tools=[send_email],
)

response = await agent.run(
    "Email the launch update to finance@example.com",
    function_invocation_kwargs={
        "user_id": "user-123",
        "tenant": "contoso",
    },
)

print(response.text)

Používejte ctx.kwargs uvnitř nástroje místo deklarování deky **kwargs na volatelném nástroji. Starší **kwargs nástroje stále fungují kvůli kompatibilitě, ale před ga se odeberou.

Jakýkoli parametr, který FunctionInvocationContext je označený jako vložený kontextový parametr modulu runtime bez ohledu na jeho název, a není vystavený ve schématu JSON zobrazeném modelu. Pokud zadáte explicitní model schématu nebo vstupu, je jako vložený kontextový parametr rozpoznán také prostý neoznačený ctx parametr.

Pokud je hodnota dlouhodobý stav nástroje nebo závislost místo dat pro vyvolání, nechejte ji na instanci function_invocation_kwargstřídy nástroje místo předávání . Tento vzor najdete v tématu Vytvoření třídy s více nástroji funkcí.

Middleware funkce přijímá stejný kontext.

Middleware funkce používá stejný FunctionInvocationContext objekt, který nástroje přijímají. To znamená, že middleware může kontrolovat context.arguments, context.kwargs, context.sessiona context.result.

from collections.abc import Awaitable, Callable

from agent_framework import FunctionInvocationContext
from agent_framework.openai import OpenAIResponsesClient


async def enrich_tool_runtime_context(
    context: FunctionInvocationContext,
    call_next: Callable[[], Awaitable[None]],
) -> None:
    context.kwargs.setdefault("tenant", "contoso")
    context.kwargs.setdefault("request_source", "middleware")
    await call_next()


agent = OpenAIResponsesClient().as_agent(
    name="Notifier",
    instructions="Send email updates.",
    tools=[send_email],
    middleware=[enrich_tool_runtime_context],
)

Kontrakt middlewaru používá call_next() bez argumentů. Před voláním ztlumte context.kwargs a vybraný nástroj tyto hodnoty zobrazí prostřednictvím injektáže FunctionInvocationContext.

Použití session= pro sdílený stav modulu runtime

from typing import Annotated

from agent_framework import FunctionInvocationContext, tool
from agent_framework.openai import OpenAIResponsesClient


@tool(approval_mode="never_require")
def remember_topic(
    topic: Annotated[str, "Topic to remember."],
    ctx: FunctionInvocationContext,
) -> str:
    if ctx.session is None:
        return "No session available."

    ctx.session.state["topic"] = topic
    return f"Stored {topic!r} in session state."


agent = OpenAIResponsesClient().as_agent(
    name="MemoryAgent",
    instructions="Remember important topics.",
    tools=[remember_topic],
)

session = agent.create_session()
await agent.run("Remember that the budget review is on Friday.", session=session)
print(session.state["topic"])

Předat relaci explicitně session= a číst z ctx.session. Přístup k relacím už nemusí procházet moduly runtime kwargs.

Sdílení stavu relace s delegovanými agenty

Když je agent vystaven jako nástroj prostřednictvím as_tool(), funkce runtime kwargs již prochází ctx.kwargs. Přidat propagate_session=True pouze tehdy, když má sub-agent sdílet volajícího AgentSession.

from agent_framework import FunctionInvocationContext, tool
from agent_framework.openai import OpenAIResponsesClient


@tool(description="Store findings for later steps.")
def store_findings(findings: str, ctx: FunctionInvocationContext) -> None:
    if ctx.session is not None:
        ctx.session.state["findings"] = findings


client = OpenAIResponsesClient()

research_agent = client.as_agent(
    name="ResearchAgent",
    instructions="Research the topic and store findings.",
    tools=[store_findings],
)

research_tool = research_agent.as_tool(
    name="research",
    description="Research a topic and store findings.",
    arg_name="query",
    propagate_session=True,
)

U propagate_session=Truedelegovaného agenta se zobrazí stejný ctx.session stav jako volající. False Ponechte ho tak, aby izoloval podřízeného agenta ve vlastní relaci.

Vlastní chatovací klienti a agenti

Pokud implementujete vlastní veřejné run() nebo get_response() metody, přidejte do podpisu explicitní kontejnery modulu runtime.

from collections.abc import Mapping, Sequence
from typing import Any

from agent_framework import ChatOptions, Message


async def get_response(
    self,
    messages: Sequence[Message],
    *,
    options: ChatOptions[Any] | None = None,
    function_invocation_kwargs: Mapping[str, Any] | None = None,
    client_kwargs: Mapping[str, Any] | None = None,
    **kwargs: Any,
):
    ...

Používá se function_invocation_kwargs pro toky volání nástrojů a client_kwargs pro chování specifické pro klienta. Předávání hodnot specifických pro klienta přímo prostřednictvím veřejného **kwargs je pouze cesta kompatibility a měla by se považovat za zastaralá. Stejně tak definování nových nástrojů s kompatibilitou pouze s **kwargs migrací – místo toho spotřebovávají data modulu runtime prostřednictvím vloženého objektu kontextu.

Další kroky

poskytovatelé