Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 98 additions & 2 deletions docs/specs/004-python-function-calling-loop.md

Large diffs are not rendered by default.

2 changes: 2 additions & 0 deletions python/packages/ag-ui/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,8 @@ AG-UI protocol integration for building agent UIs with the AG-UI standard.
object AG-UI is handed, so a wrapper agent that does not forward it would silently drop the protection.
`_RESERVED_SERVICE_SESSION_STATE_KEYS` therefore reserves such keys unconditionally; add a key there whenever
it names a remote resource that the server's own credentialed call addresses.
- Background tool recovery evidence (`_background_tool_recovery`) is protected from request Shared State even through
opaque wrappers, but retained in private Session Continuation State in both history modes.
- `ToolApprovalMiddleware` names its session state with an application-chosen `source_id`, which a wrapper can hide
from the agent AG-UI is handed. Tool approval authority is therefore also protected by shape, not only by name: a
client Shared State value holding a non-empty `rules`, `queued_approval_requests` or `collected_approval_responses`
Expand Down
4 changes: 4 additions & 0 deletions python/packages/ag-ui/agent_framework_ag_ui/_agent_run.py
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,7 @@
AG_UI_INTERNAL_METADATA_KEYS = {"ag_ui_thread_id", "ag_ui_run_id", "current_state", "forwarded_props"}
_COLLECTED_APPROVAL_RESPONSES_KEY = "collected_approval_responses"
_PROVIDER_SERVICE_SESSION_ID_STATE_KEY = "__ag_ui_provider_service_session_id"
_BACKGROUND_TOOL_RECOVERY_STATE_KEY = "_background_tool_recovery"

# Provider-owned session-state keys reserved unconditionally, independent of what the agent declares through
# ``service_session_state_keys``. Agents are expected to declare their own keys, but that resolves through the
Expand Down Expand Up @@ -2653,6 +2654,7 @@ def _request_state_protected_keys(agent: SupportsAgentRun) -> set[str]:
_TOOL_APPROVAL_STATE_KEY,
InMemoryHistoryProvider.DEFAULT_SOURCE_ID,
MESSAGE_INJECTION_PENDING_MESSAGES_STATE_KEY,
_BACKGROUND_TOOL_RECOVERY_STATE_KEY,
*(provider.source_id for provider in context_providers),
*_provider_service_session_state_keys(agent),
*_fides_session_state_keys(agent),
Expand Down Expand Up @@ -2725,6 +2727,8 @@ def _provider_service_session_state_keys(agent: SupportsAgentRun) -> set[str]:
declared = getattr(agent, "service_session_state_keys", ())
if isinstance(declared, (list, tuple, set, frozenset)):
keys.update(key for key in cast(Collection[Any], declared) if isinstance(key, str))
# Recovery evidence stays private and durable even when model history is client-managed.
keys.discard(_BACKGROUND_TOOL_RECOVERY_STATE_KEY)
return keys


Expand Down
49 changes: 49 additions & 0 deletions python/packages/ag-ui/tests/ag_ui/test_run.py
Original file line number Diff line number Diff line change
Expand Up @@ -3811,6 +3811,55 @@ def capture_state(*args: Any, **kwargs: Any) -> Any:
assert observed_state == [{"client_value": "available"}]


@pytest.mark.parametrize("use_service_session", [False, True])
@pytest.mark.parametrize("declares_keys", [False, True], ids=["opaque-wrapper", "declared-agent"])
async def test_background_recovery_state_is_private_and_cannot_be_overwritten(
use_service_session: bool, declares_keys: bool
) -> None:
from agent_framework_ag_ui import AgentFrameworkAgent, InMemoryAGUIThreadSnapshotStore

stub = StubAgent()
key = "_background_tool_recovery"
if declares_keys:
setattr(stub, "service_session_state_keys", frozenset({key}))
observed_state: list[dict[str, Any]] = []
original_run = stub.run
trusted_state = {"pending": {"token": "trusted-response"}, "handled": ["already-executed"]}

def capture_state(*args: Any, **kwargs: Any) -> Any:
session = kwargs["session"]
observed_state.append(dict(session.state))
session.state[key] = trusted_state
return original_run(*args, **kwargs)

stub.run = capture_state # type: ignore[assignment, method-assign] # ty: ignore[invalid-assignment]
store = InMemoryAGUIThreadSnapshotStore()
agent = AgentFrameworkAgent(
agent=stub,
snapshot_store=store,
use_service_session=use_service_session,
service_session_id_from_thread_id=use_service_session,
)
payload: dict[str, Any] = {
"thread_id": "recovery-thread",
"__ag_ui_snapshot_scope": "test",
"messages": [{"role": "user", "content": "Hello"}],
"state": {key: {"pending": None, "handled": []}, "client_value": "available"},
}
_ = [event async for event in agent.run({**payload, "run_id": "first-run"})]
snapshot = await store.get(scope="test", thread_id="recovery-thread")
assert snapshot is not None
assert snapshot.session_state is not None
assert snapshot.session_state[key] == trusted_state
assert snapshot.state is not None
assert snapshot.state[key] == payload["state"][key]
_ = [event async for event in agent.run({**payload, "run_id": "second-run"})]
assert observed_state == [
{"client_value": "available"},
{key: trusted_state, "client_value": "available"},
]


def test_tool_approval_authority_is_recognized_by_shape_not_encoding() -> None:
"""Any non-empty approval list is authority whatever its item encoding; inert shapes are not."""
authority_states: list[Any] = [
Expand Down
1 change: 1 addition & 0 deletions python/packages/core/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ agent_framework/
├── _clients.py # Chat client base classes and protocols
├── _types.py # Core types (Message, ChatResponse, Content, etc.)
├── _tools.py # Tool definitions and function invocation
├── _tool_recovery.py # Session-backed execution evidence and delivery checkpoints for background responses
├── _vectors.py # Vector store models, CRUD/search abstractions, and protocols
├── _middleware.py # Middleware system for request/response interception
├── _sessions.py # AgentSession and context provider abstractions
Expand Down
2 changes: 2 additions & 0 deletions python/packages/core/agent_framework/_agents.py
Original file line number Diff line number Diff line change
Expand Up @@ -1752,6 +1752,8 @@ async def _prepare_run_context(
from ._tools import _APPROVAL_SESSION_IS_AUTHORITATIVE_KEY # pyright: ignore[reportPrivateUsage]

effective_client_kwargs.pop(_APPROVAL_SESSION_IS_AUTHORITATIVE_KEY, None)
if callable(getattr(self.client, "_background_tool_recovery_scope", None)):
effective_client_kwargs["_background_tool_recovery_inputs"] = input_messages
if active_session is not None:
effective_client_kwargs["session"] = active_session
effective_client_kwargs[_APPROVAL_SESSION_IS_AUTHORITATIVE_KEY] = not framework_created_session
Expand Down
Loading
Loading