Laufzeitkontext

In C# wird der Laufzeitkontext in der Regel durch den AgentRunOptions oder den benutzerdefinierten Sitzungszustand übergeben. Middleware kann auf Sitzungseigenschaften zugreifen und Optionen ausführen, um Laufzeitentscheidungen zu treffen.

Der Python-Laufzeitkontext wird auf drei öffentliche Oberflächen aufgeteilt:

• session= für Unterhaltungsstatus und Verlauf.
• function_invocation_kwargs= für Werte, die nur Tools oder Funktions-Middleware angezeigt werden sollen.
• client_kwargs= für chat-clientspezifische Daten oder Client-Middleware-Konfiguration.

Verwenden Sie die kleinste Oberfläche, die den Daten entspricht. Dadurch werden Die Tooleingaben explizit beibehalten und verhindern, dass nur Clientmetadaten in die Toolausführung eingespeckt werden.

Auswählen des richtigen Laufzeit-Buckets

Übergeben von Nur-Tool-Laufzeitwerten

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)

Verwenden Sie ctx.kwargs innerhalb des Tools, anstatt eine Decke **kwargs auf dem Tool zu deklarieren, das aufgerufen werden kann. Legacytools **kwargs funktionieren weiterhin zur Kompatibilität, werden jedoch vor ga entfernt.

Jeder Parameter, der wie FunctionInvocationContext der injizierte Laufzeitkontextparameter behandelt wird, unabhängig vom Namen und nicht im JSON-Schema, das dem Modell angezeigt wird, verfügbar gemacht wird. Wenn Sie ein explizites Schema-/Eingabemodell angeben, wird auch ein unanmerkter Parameter namens ctx "Nur nicht kommentiert" als der injizierte Kontextparameter erkannt.

Wenn der Wert ein langlebiger Toolstatus oder eine Abhängigkeit anstelle von Daten per Aufruf ist, behalten Sie ihn in einer Toolklasseninstanz bei, anstatt ihn zu function_invocation_kwargsübergeben. Dieses Muster finden Sie unter Erstellen einer Klasse mit mehreren Funktionstools.

Funktions-Middleware empfängt denselben Kontext

Funktions-Middleware verwendet dasselbe FunctionInvocationContext Objekt, das Tools empfangen. Dies bedeutet, dass Middleware die Prüfung context.arguments, context.kwargs, , context.sessionund 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],
)

Der Middleware-Vertrag verwendet call_next() ohne Argumente. Stummschalten context.kwargs sie vor dem Aufrufen, und das ausgewählte Tool sieht diese Werte durch die eingefügte FunctionInvocationContext.

Wird für den freigegebenen Laufzeitstatus verwendet session=

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"])

Übergeben Sie die Sitzung explizit mit session= und lesen Sie sie aus ctx.session. Der Sitzungszugriff muss nicht mehr durch Laufzeit-Kwargs reisen.

Freigeben des Sitzungsstatus für delegierte Agents

Wenn ein Agent als Tool as_tool()verfügbar gemacht wird, fließen laufzeitfunktion kwargs bereits durch ctx.kwargs. Fügen Sie nur hinzu propagate_session=True , wenn der Unter-Agent die Anrufer AgentSessionteilen soll.

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

Mit propagate_session=Truedem delegierten Agent wird derselbe ctx.session Zustand wie der Anrufer angezeigt. Lassen Sie es False , um den untergeordneten Agent in einer eigenen Sitzung zu isolieren.

Benutzerdefinierte Chatclients und Agents

Wenn Sie benutzerdefinierte öffentliche run() oder get_response() Methoden implementieren, fügen Sie der Signatur die expliziten Laufzeit-Buckets hinzu.

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,
):
    ...

Wird für Toolaufrufflüsse und client_kwargs für clientspezifisches Verhalten verwendetfunction_invocation_kwargs. Das direkte Übergeben clientspezifischer Werte über öffentliche **kwargs Daten ist nur ein Kompatibilitätspfad und sollte als veraltet behandelt werden. Ebenso ist die Definition neuer Tools **kwargs nur für die Migrationskompatibilität geeignet – verwenden Sie stattdessen Laufzeitdaten über das injizierte Kontextobjekt.