* Python: A2UI (Agent-to-UI) support for the AG-UI adapter
Adds an in-package _a2ui module to agent-framework-ag-ui delivering
progressive-streaming, error-recovery, and sub-agent-based A2UI surface
generation, reusing the shared ag-ui-a2ui-toolkit. Includes example
agents, a unit suite, and two bridge fixes (strip unanswered tool calls
from replayed history; suppress the terminal MESSAGES_SNAPSHOT for A2UI
runs to keep streamed order stable).
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review feedback — declarative wiring, no agent swap
Reworks A2UI so it no longer swaps the agent object mid-run, and fixes the
issues that swap caused.
- Drive A2UI through a dedicated runner used only for the stream call; keep
the original agent bound so protected-state-key computation, approval
resolution, and continuation serialization still read its real
context_providers and client (no more provider-namespace or approval
middleware loss).
- Hand the forwarded AG-UI context to the runner directly instead of stamping
it onto run-option additional_properties. That channel leaked the slice to
the provider SDK on any run carrying AG-UI context, including non-A2UI runs
where nothing stripped it back. Removes the stamp/strip/read helpers and the
dead .NET-shaped path.
- Suppress the terminal MESSAGES_SNAPSHOT off whether A2UI actually drove the
run, not the literal tool names, so an unrelated user tool named
"generate_a2ui" keeps its snapshot.
- Fail loud with an install hint when A2UI is requested but the toolkit isn't
installed, instead of advertising render_a2ui with no executor.
- Include the agent's own default tools in the no-double-injection check so an
already-wired agent doesn't crash on a duplicate tool name.
- Execute ordinary developer tools called in the same turn as generate_a2ui
(the declaration-only tool poisons the inner batch invocation), so a
"look up data then render it" turn no longer skips the backend call.
- Attribute nameless streaming argument deltas by the provider tool-call index
so interleaved parallel calls don't cross-contaminate; the OpenAI chat client
preserves that index on the content.
Adds tests for the mixed-batch execution, index-based fragment attribution,
and the default-tool duplicate check.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review round 2 — mixed-batch pipeline, client tools, snapshot
- Mixed-batch (a tool called in the same turn as generate_a2ui): execute
server tools through the agent's real function-invocation pipeline (client
function_middleware + config), the same path approval-resume uses, instead
of a direct tool.invoke() that bypassed middleware/context/session.
- Look up mixed-batch tools across incoming AND the agent's own default tools,
so a server tool wired only on the agent (no runtime tools=) still executes.
- Leave declaration-only client tools (func=None) as user-input requests
instead of synthesizing a local result, preserving the resumable client-tool
flow.
- Recognize a manually enable_a2ui()-wrapped agent when deciding to suppress
the terminal MESSAGES_SNAPSHOT, so the ordering fix also covers that path.
- Remove .NET-specific comments from the Python module.
Adds tests: server-tool execution runs through middleware, default-tool
execution, client declaration-only tool left as user-input.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review round 2 — fold context wrapper, typed runner
Consolidates A2UI wiring into one owner, per review:
- Fold the context-prepend (former AGUIContextAgent) into A2UIAgent, which now
prepends the forwarded catalog + guidelines as a system message itself.
Removes the extra agent type (matching the langgraph/strands adapters, which
have no separate context agent).
- Make A2UIAgent the typed runner interface: it carries the render tool(s) to
strip (drop_tool_names) and is recognized via is_a2ui_runner(). plan_a2ui_injection
now returns the runner (or None) instead of a bare dict, so no private plan keys
leak into the host and the host no longer tracks activation separately —
is_a2ui_runner() covers both the auto-injected and manual enable_a2ui() paths.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI — bridge test for client tool + generate_a2ui in one turn
End-to-end through run_agent_stream: a turn that calls a declaration-only client
tool alongside generate_a2ui surfaces the client tool as a resumable frontend
tool call (START/ARGS/END, no server-synthesized result) so the frontend
executes and resumes it, the A2UI surface still renders, the run finishes, and
no terminal MESSAGES_SNAPSHOT is emitted (manual enable_a2ui path). Confirms the
mixed-batch client-tool contract on the AG-UI wire, not just at the agent level.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review round 3 — manual-path delegation, per-request context, facade
- A2UIAgent delegates client / default_options / context_providers to the wrapped
agent, so a manually enable_a2ui()-wrapped runner keeps the inner agent's
configured tools, provider-owned state protection, and approval middleware that
the auto-injected path already preserves.
- Take the AG-UI context slice per run (a2ui_context kwarg the host passes each
request) instead of only at construction, so a reused runner never serves stale
catalog/guidelines.
- Remove the deleted AGUIContextAgent from the package facade's __all__ and lazy
exports (it no longer resolves) and drop the remaining doc references to it.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review round 3 — mixed-batch reuses the core invocation controls
Reworks server-tool execution batched with generate_a2ui so it goes through the
shared function-invocation owner faithfully instead of a partial re-implementation:
- Pass the run's invocation session and the full function-middleware pipeline
(static client middleware plus runtime middleware) into the execution.
- Honor function_invocation_configuration["enabled"] and the shared per-request
max_function_calls budget, tracked cumulatively across A2UI planner rounds, so a
side-effecting tool cannot run once per round or run while invocation is disabled.
- Preserve non-result control contents (e.g. a function_approval_request for an
always_require tool) and the executor's termination signal instead of filtering to
function_result, and surface them on the wire.
- Stop the run instead of re-entering the planner whenever the turn carries calls it
cannot safely replay — client tools awaiting the frontend, deferred/over-budget or
approval-pending server tools, or a termination request — so an unanswered assistant
tool_call is never replayed as unbalanced history.
Tests: cumulative budget cap across rounds, invocation-disabled skip, approval request
surfaced + run stops, and the bridge test now asserts the planner is not re-entered.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review round 4 — core batch executor, budget/iteration parity
- Add a core-owned execute_function_call_batch() to agent_framework._tools that
builds the function-middleware pipeline (static + runtime, normalizing bare
objects and expanding MiddlewareBundles via categorize_middleware), normalizes
config, threads the invocation session, and returns a structured result
(results / control / should_terminate). A2UI's mixed-batch server execution now
delegates to it instead of reproducing the pipeline/session/result handling, so
a runtime `middleware=<bare>` or a bundle no longer raises or is silently skipped,
and future core policy changes stay in one place.
- Charge generate_a2ui against the per-request max_function_calls budget (each is a
render-subagent invocation) and cap the planner rounds by max_iterations, so a
generate-only planner can no longer run more render calls than the configured
limits.
Tests: generate-only planner honors the call budget and max_iterations; the
mixed-batch budget test accounts for generate also charging.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review round 5 — force tools off on the final narration turn
The final narration turn started a fresh inner_agent.run() with tools still
enabled, so after the planner rounds/budget were spent it could execute another
full batch of server/default tools and exceed max_function_calls / max_iterations.
Set tool_choice="none" on that turn so it is a pure narration with no tool
execution, matching the core loop's budget-exhausted final response.
Test: the final narration turn's options carry tool_choice="none".
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review round 5 — move the budget lifecycle into a core owner
Add a core-owned FunctionCallBudget to agent_framework._tools that owns the
per-request accounting the core loop enforces: the invocation toggle, the
cumulative max_function_calls budget, the max_iterations round cap, and the
tools-off final-response options. execute_function_call_batch now takes a budget
and returns the deferred (unrun) calls.
A2UIAgent's planner loop no longer reimplements any of this — it holds one budget
object and asks it (rounds_remaining / take / exhausted / final_response_options),
so server tools, generate_a2ui, the round cap, and the final tools-off turn all go
through the single core owner. This removes the split that let the final turn start
a fresh budget, and keeps mixed A2UI turns aligned with core policy changes.
Tests: core budget primitive (take/exhausted/rounds/final-options); invocation
disabled now runs no server tool AND no surface (matches the core loop).
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review round 5 follow-up — keep budgeting local, narrate on budget exhaustion
Per review, the core is not the place for a second budget abstraction: remove the
FunctionCallBudget class from agent_framework._tools (execute_function_call_batch,
which was the requested shared executor, stays). A2UIAgent honors the inner agent's
function-invocation configuration locally again — the invocation toggle, the
cumulative max_function_calls budget (charged by server tools and generate_a2ui),
and the max_iterations round cap.
Also fix the reported gap: when the call budget is exhausted (e.g. max_function_calls=1
spent on the first generate_a2ui), the run now breaks to the tools-off final narration
turn instead of returning after the surface, so it produces a closing assistant
response — matching the iteration-cap path and the core loop. Calls awaiting external
resolution (client tools, deferred, approval, termination) still end the run without
that final turn, since a follow-up run resumes them.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI — feed the current surface to the budget-exhausted final narration
On budget exhaustion the loop broke before appending this round's assistant
tool_call(s) and results to history, so the tools-off final narration turn saw
only the original user messages and could not narrate the generate_a2ui result it
had just produced. Append the round's assistant/tool pair before breaking so the
final turn receives it. The test now asserts the final turn's messages include the
just-produced surface.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI — keep batch execution in the adapter; fix CI typing
Per review, don't add A2UI-specific abstractions to core: remove
execute_function_call_batch / FunctionCallBatchExecution from
agent_framework._tools. A2UIAgent's _execute_server_tools now runs the mixed
batch inline using the framework's existing helpers (_try_execute_function_call_groups
plus categorize_middleware for bare/bundle middleware normalization) with the run's
session, config, and middleware — the same helpers the AG-UI approval path uses — so
nothing adapter-specific lives in core.
Also fix the CI typing check: annotate the A2UI test doubles and helpers so mypy,
pyrefly, and ty pass over the test module (mixed-shape result tuples, a nullable
envelope helper, and duck-typed fakes passed where protocols are expected).
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI — propagate MiddlewareFailure through the inline server-tool path; generic non-leaking error results; fix ty test typing
- _execute_server_tools now re-raises MiddlewareFailure so a fail-closed
authorization/guardrail abort stops the run instead of being folded into an
error result that would still render a surface (matches the core loop).
- Ordinary execution failures return core's generic 'Error: Function failed.'
message; the raw exception text rides the non-model-visible exception field
and is only exposed when include_detailed_errors is enabled, so credentials/
provider payloads/tenant data cannot leak to the model.
- Add ty suppressions on the two duck-typed test constructors (ty does not honor
mypy-style '# type: ignore[arg-type]') to clear the Test Typing Checks gate.
- Cover both behaviors with tests (MiddlewareFailure aborts without rendering;
tool error result is generic and non-leaking).
---------
Signed-off-by: ran <ran@copilotkit.ai>
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Ran Shemtov
59ecceba03