Körningskontext

Körningskontext ger mellanprogram åtkomst till information om den aktuella körningsmiljön och begäran. Detta möjliggör mönster som konfiguration per session, användarspecifikt beteende och dynamiskt mellanprogramsbeteende baserat på körningsvillkor.

I C# skickas körningskontext vanligtvis via AgentRunOptions eller anpassat sessionstillstånd. Mellanprogram kan komma åt sessionsegenskaper och körningsalternativ för att fatta körningsbeslut.

Tips/Råd

Mer information om hur mellanprogramsomfånget påverkar åtkomsten till körningskontext finns på sidan Agent kontra Körningsomfång .

Python-körningskontexten delas upp på tre offentliga ytor:

session= för konversationstillstånd och historik.
function_invocation_kwargs= för värden som endast verktyg eller funktionsmellanprogram ska se.
client_kwargs= för konfiguration av chattklientspecifika data eller klientmellanprogram.

Använd den minsta ytan som passar data. Detta håller verktygsindata explicita och undviker att läcka enbart klientmetadata till verktygskörning.

Tips/Råd

Behandla function_invocation_kwargs som ersättning för det gamla mönstret för att skicka godtyckliga offentliga **kwargs till agent.run() eller get_response().

Välj rätt körningshink

Användningsfall	API-yta	Nås från
Dela konversationstillstånd, tjänstsessions-ID eller historik	`session=`	`ctx.session`, `AgentContext.session`
Endast verktyg eller funktionsmellanprogram behöver passera körningsvärden	`function_invocation_kwargs=`	`FunctionInvocationContext.kwargs`
Skicka klientspecifika körningsvärden eller konfiguration av mellanprogram för klienten	`client_kwargs=`	anpassade `get_response(..., client_kwargs=...)` implementeringar

Skicka körningsvärden endast för verktyg

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)

Använd ctx.kwargs inuti verktyget i stället för att deklarera filten **kwargs på verktyget som kan anropas. Äldre **kwargs verktyg fungerar fortfarande för kompatibilitet, men tas bort före ga.

Alla parametrar som kommenteras som FunctionInvocationContext behandlas som den inmatade körningskontextparametern, oavsett namn, och den exponeras inte i JSON-schemat som visas för modellen. Om du anger en explicit schema-/indatamodell identifieras även en oannoterad parameter med namnet ctx som den inmatade kontextparametern.

Om värdet är ett långvarigt verktygstillstånd eller ett beroende i stället för data per anrop behåller du det på en verktygsklassinstans i stället för att skicka det via function_invocation_kwargs. Det här mönstret finns i Skapa en klass med flera funktionsverktyg.

Funktionens mellanprogram tar emot samma kontext

Funktionens mellanprogram använder samma FunctionInvocationContext objekt som verktygen tar emot. Det innebär att mellanprogram kan inspektera context.arguments, context.kwargs, context.sessionoch 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],
)

Mellanprogramskontraktet använder call_next() utan argument. Mutera context.kwargs innan du anropar det, och det valda verktyget ser dessa värden genom dess inmatade FunctionInvocationContext.

Använd `session=` för tillstånd för delad körning

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

Skicka sessionen explicit med session= och läs den från ctx.session. Sessionsåtkomst behöver inte längre färdas via runtime kwargs.

När en agent exponeras som ett verktyg via as_tool()flödar runtime-funktionen kwargs redan genom ctx.kwargs. Lägg bara till propagate_session=True när underagenten ska dela anroparens 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,
)

Med propagate_session=Trueser den delegerade agenten samma ctx.session tillstånd som anroparen. Låt den False isolera den underordnade agenten i sin egen session.

Anpassade chattklienter och agenter

Om du implementerar anpassade offentliga run() eller get_response() metoder lägger du till explicita körnings bucketar i signaturen.

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

Används function_invocation_kwargs för verktygsanropsflöden och client_kwargs för klientspecifikt beteende. Att skicka klientspecifika värden direkt via offentlig **kwargs är bara en kompatibilitetssökväg och bör behandlas som inaktuell. På samma sätt är definitionen av nya verktyg med **kwargs kompatibilitet endast för migrering – förbruka körningsdata via det inmatade kontextobjektet i stället.

Nästa steg

Tjänsteleverantörer

Feedback

Var den här sidan till hjälp?

Last updated on 2026-03-17

Dela via