Bagikan melalui

Konteks Runtime

Konteks runtime menyediakan middleware dengan akses ke informasi tentang lingkungan dan permintaan eksekusi saat ini. Ini memungkinkan pola seperti konfigurasi per sesi, perilaku khusus pengguna, dan perilaku middleware dinamis berdasarkan kondisi runtime.

Dalam C#, konteks runtime biasanya diteruskan AgentRunOptions atau status sesi kustom. Middleware dapat mengakses properti sesi dan menjalankan opsi untuk membuat keputusan runtime.

Petunjuk / Saran

Lihat halaman Agen vs Jalankan Cakupan untuk informasi tentang bagaimana cakupan middleware memengaruhi akses ke konteks runtime.

Konteks runtime Python dibagi di tiga permukaan publik:

  • session= untuk status percakapan dan riwayat.
  • function_invocation_kwargs= untuk nilai yang hanya akan dilihat alat atau middleware fungsi.
  • client_kwargs= untuk data khusus klien obrolan atau konfigurasi middleware klien.

Gunakan permukaan terkecil yang sesuai dengan data. Ini membuat input alat tetap eksplisit dan menghindari kebocoran metadata khusus klien ke dalam eksekusi alat.

Petunjuk / Saran

Perlakukan function_invocation_kwargs sebagai pengganti pola lama dari meneruskan publik **kwargs arbitrer ke agent.run() atau get_response().

Pilih wadah runtime yang tepat

Skenario penggunaan Permukaan API Diakses dari
Bagikan status percakapan, ID sesi layanan, atau riwayat session= ctx.session, AgentContext.session
Meneruskan nilai runtime hanya alat atau kebutuhan middleware fungsi function_invocation_kwargs= FunctionInvocationContext.kwargs
Meneruskan nilai runtime khusus klien atau konfigurasi middleware klien client_kwargs= implementasi kustom get_response(..., client_kwargs=...)

Meneruskan nilai runtime khusus alat

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)

Gunakan ctx.kwargs di dalam alat alih-alih mendeklarasikan selimut **kwargs pada alat yang dapat dipanggil. Alat warisan **kwargs masih berfungsi untuk kompatibilitas, tetapi akan dihapus sebelum GA.

Parameter apa pun yang dianotasi seperti FunctionInvocationContext yang diperlakukan sebagai parameter konteks runtime yang disuntikkan, terlepas dari namanya, dan tidak diekspos dalam skema JSON yang ditunjukkan ke model. Jika Anda memberikan model skema/input eksplisit, parameter tanpa anotasi biasa bernama ctx juga dikenali sebagai parameter konteks yang disuntikkan.

Jika nilainya adalah status alat berumur panjang atau dependensi daripada data per pemanggilan, simpan pada instans kelas alat alih-alih meneruskannya melalui function_invocation_kwargs. Untuk pola tersebut, lihat Membuat kelas dengan beberapa alat fungsi.

Middleware fungsi menerima konteks yang sama

Middleware fungsi menggunakan objek yang sama FunctionInvocationContext dengan yang diterima alat. Itu berarti middleware dapat memeriksa context.arguments, , context.sessioncontext.kwargs, dan 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],
)

Kontrak middleware menggunakan call_next() tanpa argumen. Bermutasi context.kwargs sebelum memanggilnya, dan alat yang dipilih melihat nilai-nilai tersebut melalui yang disuntikkan FunctionInvocationContext.

Gunakan session= untuk status runtime bersama

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

Berikan sesi secara eksplisit dengan session= dan baca dari ctx.session. Akses sesi tidak perlu lagi melakukan perjalanan melalui kwarg runtime.

Berbagi status sesi dengan agen yang didelegasikan

Ketika agen diekspos sebagai alat melalui as_tool(), fungsi runtime kwargs sudah mengalir melalui ctx.kwargs. Tambahkan propagate_session=True hanya ketika sub-agen harus berbagi penelepon 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,
)

Dengan , agen yang didelegasikan melihat status yang sama ctx.session dengan propagate_session=Truepemanggil. False Biarkan untuk mengisolasi agen anak dalam sesinya sendiri.

Klien dan agen obrolan kustom

Jika Anda menerapkan publik run() atau get_response() metode kustom, tambahkan wadah runtime eksplisit ke tanda tangan.

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

Gunakan function_invocation_kwargs untuk alur pemanggilan alat dan client_kwargs untuk perilaku khusus klien. Meneruskan nilai khusus klien secara langsung melalui publik **kwargs hanyalah jalur kompatibilitas dan harus diperlakukan sebagai tidak digunakan lagi. Demikian juga, menentukan alat baru dengan **kwargs adalah kompatibilitas khusus migrasi — gunakan data runtime melalui objek konteks yang disuntikkan sebagai gantinya.

Langkah selanjutnya

Gambaran Umum Middleware

  • Last updated on