Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Kontekst środowiska uruchomieniowego zapewnia oprogramowanie pośredniczące z dostępem do informacji o bieżącym środowisku wykonywania i żądaniu. Umożliwia to wzorce, takie jak konfiguracja poszczególnych sesji, zachowanie specyficzne dla użytkownika i dynamiczne zachowanie oprogramowania pośredniczącego na podstawie warunków środowiska uruchomieniowego.
W języku C# kontekst środowiska uruchomieniowego jest zwykle przekazywany przez AgentRunOptions lub niestandardowy stan sesji. Oprogramowanie pośredniczące może uzyskiwać dostęp do właściwości sesji i uruchamiać opcje w celu podejmowania decyzji dotyczących środowiska uruchomieniowego.
Tip
Zobacz stronę Agent a Zakres uruchamiania , aby uzyskać informacje na temat wpływu zakresu oprogramowania pośredniczącego na dostęp do kontekstu środowiska uruchomieniowego.
Kontekst środowiska uruchomieniowego języka Python jest podzielony na trzy publiczne powierzchnie:
-
session=dla stanu konwersacji i historii. -
function_invocation_kwargs=w przypadku wartości, które powinny być widoczne tylko dla narzędzi lub oprogramowania pośredniczącego funkcji. -
client_kwargs=w przypadku danych specyficznych dla klienta czatu lub konfiguracji oprogramowania pośredniczącego klienta.
Użyj najmniejszej powierzchni, która pasuje do danych. Dzięki temu dane wejściowe narzędzia są jawne i zapobiegają wyciekom metadanych tylko przez klienta do wykonywania narzędzi.
Tip
Traktuj function_invocation_kwargs jako zamiennik starego wzorca przekazywania dowolnych publicznych **kwargs do agent.run() lub get_response().
Wybieranie odpowiedniego zasobnika środowiska uruchomieniowego
| Przypadek użycia | Powierzchnia interfejsu API | Dostęp z |
|---|---|---|
| Udostępnianie stanu konwersacji, identyfikatorów sesji usługi lub historii | session= |
ctx.session, AgentContext.session |
| Przekazywanie wartości środowiska uruchomieniowego wymaga tylko narzędzi lub oprogramowania pośredniczącego funkcji | function_invocation_kwargs= |
FunctionInvocationContext.kwargs |
| Przekazywanie wartości środowiska uruchomieniowego specyficznego dla klienta lub konfiguracji oprogramowania pośredniczącego klienta | client_kwargs= |
implementacje niestandardowe get_response(..., client_kwargs=...) |
Przekazywanie wartości środowiska uruchomieniowego tylko dla narzędzi
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)
Użyj ctx.kwargs wewnątrz narzędzia zamiast deklarowania koca **kwargs na wywoływaniu narzędzia. Starsze **kwargs narzędzia nadal działają pod kątem zgodności, ale zostaną usunięte przed dostępnością.
Każdy parametr z adnotacjami FunctionInvocationContext jest traktowany jako parametr kontekstu wstrzykniętego środowiska uruchomieniowego, niezależnie od jego nazwy, i nie jest uwidoczniony w schemacie JSON pokazanym w modelu. Jeśli podasz jawny model schematu/danych wejściowych, zwykły nieoznakowany parametr o nazwie ctx jest również rozpoznawany jako wstrzykiwany parametr kontekstu.
Jeśli wartość jest długotrwałym stanem narzędzia lub zależności, a nie danymi wywołania, zachowaj ją w wystąpieniu klasy narzędzi, zamiast przekazywać je za pomocą function_invocation_kwargsmetody . Aby uzyskać ten wzorzec, zobacz Tworzenie klasy z wieloma narzędziami funkcji.
Oprogramowanie pośredniczące funkcji odbiera ten sam kontekst
Oprogramowanie pośredniczące funkcji używa tego samego FunctionInvocationContext obiektu, który otrzymuje narzędzia. Oznacza to, że oprogramowanie pośredniczące może sprawdzać context.arguments, , context.kwargscontext.sessioni 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 oprogramowania pośredniczącego używa call_next() bez argumentów. Zmutuj context.kwargs przed wywołaniem metody , a wybrane narzędzie zobaczy te wartości za pomocą wprowadzonego FunctionInvocationContextelementu .
Użyj session= dla stanu współużytkowanego środowiska uruchomieniowego
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"])
Przekaż sesję jawnie session= i odczytaj ją z pliku ctx.session. Dostęp do sesji nie musi już podróżować za pośrednictwem środowiska uruchomieniowego kwargs.
Udostępnianie stanu sesji agentom delegowanym
Gdy agent jest uwidoczniony jako narzędzie za pomocą as_tool()polecenia , funkcja środowiska uruchomieniowego kwargs już przepływa przez ctx.kwargselement . Dodaj propagate_session=True tylko wtedy, gdy agent podrzędny powinien udostępnić obiekt wywołujący 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,
)
W przypadku propagate_session=Truepolecenia agent delegowany widzi ten sam ctx.session stan co obiekt wywołujący. Pozostaw go, False aby odizolować agenta podrzędnego we własnej sesji.
Niestandardowi klienci czatu i agenci
W przypadku implementowania niestandardowych metod lub get_response() publicznych run() dodaj do podpisu jawne zasobniki środowiska uruchomieniowego.
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,
):
...
Służy function_invocation_kwargs do obsługi przepływów wywołania narzędzi i client_kwargs zachowania specyficznego dla klienta. Przekazywanie wartości specyficznych dla klienta bezpośrednio za pośrednictwem publicznej **kwargs jest tylko ścieżką zgodności i powinno być traktowane jako przestarzałe. Podobnie definiowanie nowych narzędzi ze zgodnością tylko do **kwargs migracji — zamiast tego zużywaj dane środowiska uruchomieniowego za pośrednictwem wprowadzonego obiektu kontekstu.