AI & agents

Field contracts and worked examples for the ai & agents blocks — converted at build time from the repo's authoring-skill reference. Every example body is YAML; in a real doc the fence language is the block type (for example sequence … ). Schemas are strict — unknown fields are rejected. See the field contract for the at-a-glance shape of all 77 blocks, or the block catalog for live previews.

AI & agents

Purpose-built for documenting LLM agents and pipelines: the loop itself (agentloop), what one episode actually did (trace), what the model is told (prompt), and what fills the window (context). They compose — the Agent system doc playbook in the avodado authoring skill stacks all four. For the surrounding architecture (services, queues, vector stores) stay with block (kind: llm/agent gets the violet card); for one turn's message timing use sequence.

agentloop — the canonical agent-loop diagram

The environment (env, default "User") sits left, the agent card centre (model renders as a mono chip, note as small text), tools stack right (capped at 5 + "+N more"), and a memory cylinder hangs beneath only when memory: is present. The numbered arrows are fixed — ① prompt → ② tool call → ③ result (dashed) → ④ response — so keep tools to what the agent can actually call. stop renders as a "stops when:" foot pill. Use agentloop for the loop itself; use block for the deployment around it.

trace — an agent / session execution transcript

A vertical transcript — one entry per turn, each with a role chip (USER navy · ASSISTANT violet · TOOL teal · SYSTEM gray) and a card. Assistant turns may carry thinking (renders first, small italic); a tool turn is tool + args + result (mono chips, "args:" / "→"). Multi-line strings keep their line breaks, so block scalars (|) work for long output. Quote args / result — JSON braces and colons are YAML syntax. Use trace to show what one real episode did; use sequence for the timing between services.

prompt — prompt anatomy with variable highlighting

Stacked cards, one per segment, each with a coloured role kicker (SYSTEM gray · USER navy · ASSISTANT violet · TOOL teal) and the text in a mono face. Any {{variable}} token highlights as an amber chip; list those variables in vars so the legend explains where each value comes from. text containing {{ }} must be quoted — bare braces are YAML flow syntax. Use prompt for templates and system prompts; use code for actual code.

context — context-window token budget

One horizontal bar sized against window: segments left → right, leftover space as a dim "free (N)" segment, and a legend row per segment with N tokens · NN%. Zero-token segments are skipped; if the sum exceeds the window the overflow renders red past a dashed boundary with an "over budget" chip — deliberately alarming, use it to show the failure case. unit defaults to "tokens". Use context for window budgets; use a waterfall chart for latency/cost cascades and a funnel chart for conversion.