github-featured/microsoft--agent-framework
2
0
Fork 0
Code Issues Pull Requests Deployments Models Agent Notes Packages Projects Releases Wiki Activity
Files
samples/python-agui-single-agent
microsoft--agent-framework/python/packages/ag-ui/AGENTS.md
T
Evan Mattson 56c4425db2 Python: bridge AG-UI request state and session continuity (#7084) 
* Python: bridge AG-UI request state into sessions

Decisions:
- Project resolved AG-UI Shared State into the per-run AgentSession without typed restoration.
- Preserve existing local/service session identifiers and keep AG-UI state out of provider metadata.

Files changed:
- packages/ag-ui/agent_framework_ag_ui/_agent_run.py
- packages/ag-ui/tests/ag_ui/test_endpoint.py

Verification:
- uv run poe check -P ag-ui
- uv run poe test -P ag-ui (912 passed)

Notes:
- Scoped cross-run Session Continuation State remains for the next dependent issue.

* Python: persist scoped AG-UI session continuity

Decisions:
- Store private Session Continuation State atomically in scoped thread snapshots and restore it through the core AgentSession contract.
- Exclude Shared State keys, all HistoryProvider buckets, and tool approval state; request overlays evict colliding private values.
- Finalize interrupted response streams before snapshotting so provider after_run mutations are included.

Files changed:
- packages/ag-ui/agent_framework_ag_ui/_agent_run.py
- packages/ag-ui/agent_framework_ag_ui/_snapshots.py
- packages/ag-ui/tests/ag_ui/test_endpoint.py
- packages/ag-ui/tests/ag_ui/test_snapshots.py
- packages/ag-ui/AGENTS.md

Verification:
- uv run poe test -P ag-ui (921 passed)
- uv run poe check -P ag-ui
- uv run poe typing -P ag-ui

Notes:
- Lifecycle, isolation, and broader storage guidance remain for the next dependent issue.

* Python: document AG-UI session continuity lifecycle

Decisions:
- Keep scoped thread snapshots as the single reset and continuity boundary, with missing request Shared State preserving private continuation.
- Document trusted typed-restoration storage, State Authorities, custom-store round trips, and one-active-run last-writer-wins consistency.
- Verify failure, hydration privacy, scope/thread isolation, and reset mechanics through public endpoint and store seams.

Files changed:
- packages/ag-ui/README.md
- packages/ag-ui/tests/ag_ui/test_endpoint.py
- packages/ag-ui/tests/ag_ui/test_snapshots.py

Verification:
- uv run pytest -q <focused lifecycle tests> (6 passed)
- uv run poe test -P ag-ui
- uv run poe syntax -P ag-ui -C
- uv run poe typing -P ag-ui
- uv run poe check -P ag-ui
- uv run poe markdown-code-lint

Notes:
- No runtime capability probe, secondary state store, locking, or configuration flag was added.
- No blockers remain for this lifecycle and guidance slice.

* Python: harden AG-UI session continuity

* Python: isolate AG-UI request state
2026-07-14 04:55:46 +00:00

2.6 KiB
Raw Permalink Blame History

AG-UI Package (agent-framework-ag-ui)

AG-UI protocol integration for building agent UIs with the AG-UI standard.

Main Classes

  • AgentFrameworkAgent - Wraps agents for AG-UI compatibility
  • AgentFrameworkWorkflow - Wraps native Workflow objects, or accepts workflow_factory(thread_id) for thread-scoped workflow instances without subclassing
  • AGUIChatClient - Chat client that speaks AG-UI protocol
  • AGUIHttpService - HTTP service for AG-UI endpoints
  • AGUIEventConverter - Converts between Agent Framework and AG-UI events
  • add_agent_framework_fastapi_endpoint() - Add AG-UI endpoint to FastAPI app (SupportsAgentRun or Workflow)
  • InMemoryAGUIThreadSnapshotStore - Memory-only latest AG-UI Thread Snapshot store for local development, demos, and tests

Types

  • AGUIRequest / AGUIChatOptions - Request types
  • AGUIThreadSnapshot / AGUIThreadSnapshotStore - Thread snapshot model with client-replayable data, private Session Continuation State, and a scoped async store protocol
  • availableInterrupts / resume - Optional canonical AG-UI Interrupt and ResumeEntry protocol data
  • AgentState / RunMetadata - State management types
  • PredictStateConfig - Configuration for state prediction

Protocol Notes

  • Outbound custom events are emitted as AG-UI CUSTOM.
  • Usage metadata from Content(type="usage") is surfaced as CUSTOM events with name="usage".
  • Inbound custom event aliases are accepted: CUSTOM, CUSTOM_EVENT, and custom_event.
  • Multimodal user inputs support both legacy (text, binary) and draft-style (image, audio, video, document) shapes.
  • Interrupted runs complete with RUN_FINISHED.outcome.type == "interrupt" and canonical outcome.interrupts; do not document or add new flows that depend on the legacy top-level RUN_FINISHED.interrupt field.
  • Interrupt and ResumeEntry come from the ag-ui-protocol package (ag_ui.core), not from an Agent Framework-specific interrupt model.
  • SSE keepalive is endpoint-owned transport behavior configured through add_agent_framework_fastapi_endpoint(keepalive_seconds=...). It emits SSE comments only; do not add PING, HEARTBEAT, or KEEPALIVE AG-UI events, and do not add runner-level keepalive settings.

Usage

from agent_framework.ag_ui import add_agent_framework_fastapi_endpoint
from fastapi import FastAPI

app = FastAPI()
add_agent_framework_fastapi_endpoint(app, agent)

Import Path

from agent_framework.ag_ui import AGUIChatClient, add_agent_framework_fastapi_endpoint
# or directly:
from agent_framework_ag_ui import AGUIChatClient
Reference in New Issue View Git Blame Copy Permalink