Beach docs.
The architectural ideas, protocols, and guidance for working with Beach. Curated by the Beach team; presented here.
Concepts
Architecture
Get started
-
Getting Started with Beach
Install the Beach packages, wire the canonical pipeline, and watch a reply stream back in five minutes.
-
Using the Starter Scaffold
Wire @cool-ai/beach-starter into an application — orchestrator actor, channel routing, session resolution, optional research fan-out.
-
Your First Actor
How to build a minimal LLM actor in Beach — its prompt, its tool list, and the discipline of structured output through the respond() tool.
-
Your First Handler
Register a deterministic handler with the router, hook it into a routing rule, and watch it run.
-
Your First Routing Rules
Register handlers, wire a routing config, and watch events flow. A five-minute introduction.
-
Your First Agent Card
Declare what a Beach application offers — the Agent Card, A2A discovery, and peer-callable capabilities.
How-to
-
Configuring a Beach Application
Beach configuration is YAML on disk, organised along three axes — functional, environmental, secret — with per-thing files and a uniform cascade. Where to put what, and why.
-
Creating Routing Rules
How Beach's EventRouter dispatches events — routing, filtering, and cascade rules, with predicates and worked examples.
-
Manifests — Assembling and Delivering
What a Manifest is in Beach, when an Assembly Manifest is the right tool and when a Delivery Manifest is, and how each settles asynchronous coordination.
-
Setting Up Email
End-to-end walkthrough — IMAP poll inbound, SMTP outbound, gated by a Delivery Manifest, with the Beach orchestrator producing the reply.
-
Setting Up WhatsApp
End-to-end walkthrough — Meta Cloud API webhook inbound, /messages outbound, gated by a Delivery Manifest, with the Beach orchestrator producing the reply.
-
Pushing Results to the User
When background results are ready for the user, three patterns are available — render alone, render with positional inform, render with full inform. Each is correct for a different kind of surface. The choice is the designer's, made per surface.
-
Adding a Participant
How to wire a new piece of work — handler or actor — into the canonical pipeline.
-
Filter-and-distribute: per-destination views from one tool result
How Beach's FilterAndDistribute primitive takes a generalist tool's annotated record and dispatches per-destination views in parallel — to the LLM session, the UI stream, the cache, the audit log, the formatter, and federation peers — without channel-aware code in the interior.
-
Being Consumed by Other Applications
How to expose your Beach application as an A2A peer or as an MCP server, so other agents and systems can call it.
-
Non-LLM Actors
How to wire deterministic logic — triage classifiers, rules engines, database-backed responders — as an ActorFn. Same lifecycle as createLLMActor; uniform RespondCall output across the pipeline.
-
Consuming Other Agents
Call other A2A peers and MCP servers from a Beach application — agent registry, peer Agent Cards, outbound wiring.
-
Enforcing Beach's Architectural Rules with ESLint
How to wire @cool-ai/eslint-plugin-beach into a Beach application's CI so the channel-blind interior, surface-agnostic prompts, and escalated-bypass discipline are enforced mechanically rather than relying on review.
-
Durable Execution
How Beach's DurableExecutor interface persists turn state across process restarts. The interface, the in-memory reference implementation, the canonical phase taxonomy, and the wiring into EventRouter.
-
Exposing a REST API on Top of a Beach Application
A pragmatic walkthrough — building a conventional HTTP/JSON API surface that uses Beach's orchestrator and deterministic handlers underneath.
-
Authoring an A2UI Catalogue
How to design and ship a custom A2UI v0.9 catalogue for a Beach application — schema design, theming, accessibility, performance.
-
Identity and Authorisation
How Beach propagates a Principal record through the event chain, and how the Authoriser interface gives consumers a pluggable policy boundary. The shape of Principal, the role of inbound adapters, and the pattern for switching in a real policy engine.
-
Beach-Specific Anti-patterns
Recurring architectural mistakes that are particular to Beach applications, distinct from general engineering missteps. Each is described conceptually rather than by example.
-
Migrating to ActorFn
Step-by-step migration from hand-rolled orchestration plumbing (custom turn-runner code, deferred-init wireCanonicalPipeline patterns, raw provider.complete() classifier callers) to ActorFn + registerActor. The shape of ActorFn, the migration recipe for each starting shape, and the cross-cutting failure modes the migration absorbs.
-
Common A2UI Integration Mistakes
A field guide for 'my surface renders blank' and other A2UI failure modes — schema mismatches, lifecycle pitfalls, theming traps, and how to debug them.
-
respond({ domain-data }) Cookbook
How to emit structured output from an actor without falling back on JSON-in-text parsing. Three worked patterns — classifier (single decision), structured extraction (entity list), tool-result-style schema declaration — with the failure modes each replaces.
Decisions
-
Actors vs Handlers — When to Use Each
Choosing between an LLM actor and a deterministic handler for a piece of work. With criteria, examples, and migration paths.
-
Exposing Your Application Through Multiple Protocols
A Beach application speaks A2A, MCP, REST, and webhooks simultaneously. The question is not which protocol to choose, but which capabilities to expose where.
-
Streaming vs Batched Edges
Channels in Beach are either streaming or batched. The choice determines what the outbound edge subscribes to and how the orchestrator's interim parts are handled.
-
Licence stance — Beach is and remains MIT/Apache-2.0 throughout
Beach commits publicly to MIT/Apache-2.0 throughout, with no ee/ directory, no proprietary slice, and no source-available corner. Adapter packages may wrap permissive OSS only. AGPL, SSPL, ELv2, BSL, fully-proprietary, and runtime-cloud-bound packages are off-limits.
-
Routing Decisions Made by an LLM
Whether and when an LLM should make routing decisions in a Beach application. With cases where it is the right tool, and cases where it is not.
-
Adopt-vs-build gate — every CR is checked against maintained OSS
Every Beach CR proposing to build a primitive is reviewed against whether the OSS ecosystem already maintains an equivalent. If yes, the CR adapts (thin wrapper) or adopts directly. Build-the-primitive requires explicit override. The gate is the structural defence against the maintenance-budget asymmetry.
Implementation learnings
A2UI
-
A2UI host-fit conventions
Beach community convention for fitting A2UI catalogue surfaces into varying hosts. Container queries inside surfaces; --beach-host-config for optional host overrides.
-
Sub-surface composition
How a host surface invokes a derivative surface to collect a result. Three Beach EventRouter events — `subsurface:open`, `subsurface:result`, `subsurface:cancel` — composing existing A2UI primitives. Drill-down and picker worked examples.
Protocol
-
The Response Envelope
How a Beach-based agent replies to an external caller — the envelope stream, part types, and turn-state markers.
-
Agent Card
The self-description every Beach-based agent publishes so peer agents and tooling can discover its capabilities, transports, and conventions.
-
The respond() Tool
The single way an LLM actor produces output in a Beach-based system — schema, turn-state markers, and the no-free-text discipline.
-
The Tool Registry
How tools are defined, filtered per actor, and how the two-axis ToolDefinition (scope × routing) enforces capability boundaries in a Beach-based system.
-
Reference: Configuration Schemas
The JSON Schemas that describe every Beach configuration file shape. Language-portable; the same files are validated by every Beach binding.
-
Reference: beach-config CLI
Every subcommand the beach-config CLI ships with — init, validate, tree, explain, split, merge, update-models. With flags, exit codes, and worked examples.
Governance
-
Beach Contribution Policy
The architectural invariant stated precisely; what protocol-leaking means; why individually-reasonable contributions are refused.
-
The Invariant Review Criterion
The standing review check applied to every pull request against Beach core packages — how to cite it, with worked pass/fail examples.