Runtimecontext

Runtimecontext biedt middleware toegang tot informatie over de huidige uitvoeringsomgeving en aanvraag. Dit maakt patronen mogelijk, zoals configuratie per sessie, gebruikersspecifiek gedrag en dynamisch middlewaregedrag op basis van runtimevoorwaarden.

In C# wordt de runtimecontext doorgaans doorgegeven via AgentRunOptions of aangepaste sessiestatus. Middleware heeft toegang tot sessie-eigenschappen en uitvoeringsopties om runtimebeslissingen te nemen.

Aanbeveling

Zie de pagina Agent versus Bereik uitvoeren voor informatie over hoe middleware-bereik van invloed is op de toegang tot runtimecontext.

Python-runtimecontext wordt verdeeld over drie openbare oppervlakken:

• session= voor gespreksstatus en -geschiedenis.
• function_invocation_kwargs= voor waarden die alleen hulpprogramma's of functie-middleware moeten zien.
• client_kwargs= voor configuratie van chatclientspecifieke gegevens of client-middleware.

Gebruik het kleinste oppervlak dat past bij de gegevens. Hierdoor worden de invoer van hulpprogramma's expliciet en wordt voorkomen dat clientmetagegevens worden gelekt in de uitvoering van het hulpprogramma.

Aanbeveling

Behandelen function_invocation_kwargs als de vervanging voor het oude patroon van het doorgeven van willekeurige openbare **kwargs aan agent.run() of get_response().

De juiste runtime-bucket kiezen

Gebruiksituatie	API-oppervlak	Toegankelijk vanuit
Gespreksstatus, servicesessie-id's of geschiedenis delen	session=	ctx.session, AgentContext.session
Alleen hulpprogramma's of functie-middleware gebruiken om runtime-waarden door te geven	function_invocation_kwargs=	FunctionInvocationContext.kwargs
Clientspecifieke runtimewaarden of client-middlewareconfiguratie doorgeven	client_kwargs=	aangepaste get_response(..., client_kwargs=...) implementaties

Runtime-waarden voor alleen hulpprogramma's doorgeven

from typing import Annotated

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


@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 = OpenAIChatClient().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)

Gebruik ctx.kwargs in het hulpmiddel in plaats van de deken **kwargs op het aanroepbare gereedschap te declareren. Verouderde **kwargs hulpprogramma's werken nog steeds voor compatibiliteit, maar worden verwijderd vóór algemene beschikbaarheid.

Elke parameter die wordt geannoteerd zoals FunctionInvocationContext wordt behandeld als de geïnjecteerde runtimecontextparameter, ongeacht de naam, en wordt niet weergegeven in het JSON-schema dat wordt weergegeven aan het model. Als u een expliciet schema/invoermodel opgeeft, wordt een ongeannoteerde parameter met de naam ctx ook herkend als de parameter voor de geïnjecteerde context.

Als de waarde de status van het hulpprogramma lang duurt of een afhankelijkheid in plaats van aanroepgegevens per aanroep, houdt u deze op een exemplaar van de toolklasse in plaats van deze door function_invocation_kwargste geven. Zie Een klasse met meerdere functiehulpprogramma's maken voor dat patroon.

Functie-middleware ontvangt dezelfde context

Functie-middleware maakt gebruik van hetzelfde FunctionInvocationContext object dat hulpprogramma's ontvangen. Dat betekent dat middleware kan inspecteren context.arguments, context.kwargs, context.sessionen context.result.

from collections.abc import Awaitable, Callable

from agent_framework import FunctionInvocationContext
from agent_framework.openai import OpenAIChatClient


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 = OpenAIChatClient().as_agent(
    name="Notifier",
    instructions="Send email updates.",
    tools=[send_email],
    middleware=[enrich_tool_runtime_context],
)

Het middlewarecontract gebruikt call_next() zonder argumenten. Dempen context.kwargs voordat u het aanroept, en het geselecteerde hulpprogramma ziet deze waarden via de geïnjecteerde FunctionInvocationContextwaarde.

Gebruiken session= voor de status van gedeelde runtime

from typing import Annotated

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


@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 = OpenAIChatClient().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"])

Geef de sessie expliciet door met session= en lees deze van ctx.session. Sessietoegang hoeft niet langer door runtime kwargs te worden gereisd.

Sessiestatus delen met gedelegeerde agents

Wanneer een agent beschikbaar wordt gemaakt als een hulpprogramma via as_tool(), stromen runtime-functie kwargs al door ctx.kwargs. Voeg alleen toe propagate_session=True wanneer de subagent de aanroeper AgentSessionmoet delen.

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


@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 = OpenAIChatClient()

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

Met propagate_session=True, de gedelegeerde agent ziet dezelfde ctx.session status als de beller. Laat deze False staan om de onderliggende agent in een eigen sessie te isoleren.

Aangepaste chatclients en -agents

Als u aangepaste openbare run() of get_response() methoden implementeert, voegt u de expliciete runtime-buckets toe aan de handtekening.

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

Gebruiken function_invocation_kwargs voor hulpprogramma-aanroepstromen en client_kwargs voor clientspecifiek gedrag. Clientspecifieke waarden rechtstreeks doorgeven via openbaar **kwargs is alleen een compatibiliteitspad en moet worden behandeld als afgeschaft. Het definiëren van nieuwe hulpprogramma's met compatibiliteit met **kwargs alleen migraties: gebruik in plaats daarvan runtimegegevens via het geïnjecteerde contextobject.

Volgende stappen

Providers