Use the architecture to locate a decision
For application development, begin with config design. This reference is for understanding where a behavior is enforced or where to investigate a bug in the open-source library.
Trace the booking example across modules: the compiler checks the graph and creates model/execution contracts; the router selects an intent; the runtime drives dependency frames and continuation states; the mapper prepares fixed HTTP; the executor handles transport; the store serializes the interaction.
Each boundary answers a different question. A compiler test proves an unsafe config is rejected. A mapper test proves an exact outgoing value. A runtime test proves no write precedes approval. A provider test proves protocol handling. None substitutes for API authorization tests in your application.
Trace one configuration change
Adding depends_on.map affects both compilation and execution: the compiler hides top-level produced fields from model input, and runtime fills them from resolved data. Adding confirmation.required inserts a pause after request preparation. Adding response.model_view changes presentation context, not the HTTP request or raw API contract.
When investigating an issue, identify which contract changed, then reproduce it at that boundary before following the entire stack. The source map below helps you find that implementation.
Layered design
┌─────────────────────────────────────────────┐
│ Host application │
│ web · Discord · CLI · MCP │
└───────────────────┬─────────────────────────┘
│
┌───────────────────▼─────────────────────────┐
│ AgentRuntime API │
│ chat · invoke · select · confirm · cancel │
└───────────────────┬─────────────────────────┘
│
┌───────────────────▼─────────────────────────┐
│ Session + explicit state machine │
│ history · facts · frames · refs · pending │
└───────────────────┬─────────────────────────┘
│
┌───────────────────▼─────────────────────────┐
│ Hybrid routing │
│ lexical → semantic recall → model selection │
└───────────────────┬─────────────────────────┘
│
┌───────────────────▼─────────────────────────┐
│ Deterministic orchestration │
│ input → dependencies → selection → confirm │
└───────────────────┬─────────────────────────┘
│
┌───────────────────▼─────────────────────────┐
│ Execution boundary │
│ mapping → auth → HTTP → validate → redact │
└───────────────────┬─────────────────────────┘
│
┌───────────────────▼─────────────────────────┐
│ Existing REST APIs │
│ authentication · authorization · business │
└─────────────────────────────────────────────┘
Compile-time split
One YAML tool becomes two runtime representations:
tool config
│
┌──────────┴──────────┐
▼ ▼
model-facing registry execution registry
name URL/method
summary auth
input schema mappings
dependencies
retries
effect/confirmation
output validation
This limits what the model needs to see.
Main source modules
src/v2/
config/ strict schema + compiler + migration
conversation/ safe no-tool conversation/presentation prompts
execution/ explicit value-source mapping
http/ bounded transport, retry, circuit breaker
mcp/ protocol-independent tools/list + tools/call adapter
models/ model capability interface + provider adapters
observability/ rate limiter, hooks, metrics
runtime/ AgentRuntime orchestration + state transitions
security/ redaction
session/ state, facts, frames, transaction contract
tools/ lexical retrieval, semantic recall, routing, evals
Trust boundaries
Model
Trusted for language interpretation within validated schemas. Not trusted for credentials, server-owned IDs, execution authority or business facts it has not received.
Runtime
Trusted to enforce compiled policy, session continuity, mapping, confirmation, transport safeguards and redaction.
Host
Trusted to bind session IDs to real callers and supply request-scoped context/credentials.
Downstream API
Authoritative for authentication, authorization, data correctness and business side effects.
Why this matters
V2 is not “an LLM with a fetch tool.” It is a constrained execution runtime in which the language model participates only at boundaries where probabilistic interpretation is useful, while safety- and correctness-critical transitions remain deterministic.