ag_ui_a2ui/toolkit/
mod.rs

1//! Agent-side authoring: producing A2UI, not rendering it (feature `toolkit`).
2//!
3//! Everything an agent needs between "the user asked for a UI" and "valid A2UI
4//! is on the wire":
5//!
6//! | Module | Job |
7//! |---|---|
8//! | [`negotiate`] | Agree with the renderer on which catalog the surface speaks. |
9//! | [`ops`] | Build the operation stream, skipping `createSurface` on update. |
10//! | [`envelope`] | Wrap operations for transport, or report a failure. |
11//! | [`prompt`] | Assemble the generating model's prompt from catalog, context, and current surface. |
12//! | [`parser`] | Pull A2UI blocks back out of the model's response. |
13//! | [`streaming`] | Do the same incrementally, so a surface renders while it is still being generated. |
14//! | [`history`] | Recover a previously rendered surface so it can be edited. |
15//! | [`recovery`] | Validate, feed the errors back, retry — up to three times. |
16//! | [`schema`] | Hold the three schema documents; prune them to what the model needs. |
17//! | [`tools`] | The `generate_a2ui` and `render_a2ui` tool definitions. |
18//!
19//! # The loop these compose into
20//!
21//! ```text
22//!   history::find_prior_surface  ─┐
23//!   catalog::Catalog             ─┼─▶ prompt::build_subagent_prompt
24//!   the user's request           ─┘             │
25//!                                               ▼
26//!                                        the model
27//!                                               │
28//!                                  parser::parse_response
29//!                                               │
30//!                                    validate::Validator
31//!                                     ┌─────────┴─────────┐
32//!                                  valid              invalid
33//!                                     │                   │
34//!                          ops::assemble_ops   prompt::augment_prompt_with_errors
35//!                                     │                   │
36//!                 envelope::wrap_as_operations_envelope   retry (max 3)
37//! ```
38//!
39//! [`recovery::generate_with_recovery`] runs the middle of that diagram for you;
40//! the rest is there so you can assemble a different shape if your agent needs
41//! one.
42//!
43//! # Streaming is the other shape
44//!
45//! That loop waits for the whole generation before anything reaches the user,
46//! which trades latency for a validate-and-retry safety net. Swap
47//! [`parser::parse_response`] for [`streaming::StreamParser`] and the surface
48//! renders as it is generated instead: partial trees are emitted with
49//! placeholders for components still on the wire, and validation becomes a
50//! filter that holds fragments back rather than a gate that retries. Pick the
51//! first when correctness matters more than latency, the second when the user
52//! is watching.
53
54pub mod envelope;
55pub mod history;
56pub mod negotiate;
57pub mod ops;
58pub mod parser;
59pub mod prompt;
60pub mod recovery;
61pub mod schema;
62pub mod streaming;
63pub mod tools;
64
65pub use envelope::{wrap_as_operations_envelope, wrap_error_envelope};
66pub use history::{HistoryMessage, PriorSurface, find_prior_surface};
67pub use negotiate::{CatalogRegistry, ClientCapabilities, select_catalog};
68pub use ops::{Intent, SurfaceSpec, assemble_ops};
69pub use recovery::{RecoveredSurface, RecoveryActivity, RecoveryOptions, generate_with_recovery};
70pub use schema::SchemaBundle;
71pub use streaming::StreamParser;
72pub use tools::{ToolDefinition, generate_a2ui_tool, render_a2ui_tool};
ag_ui_a2ui/toolkit/mod.rs

ag_ui_a2ui/toolkit/
mod.rs
