Examples index¶

Every directory under examples/ is a self-contained, runnable demonstration of one framework capability, ordered by number from "hello world" to full SaaS scaffolds. Run them from the repo root; most compile with a build_agents.py and are invoked with opencode run from their build/ directory (see examples/README.md for prerequisites — several exercise real LLM backends).

uv run python examples/00_hello/build_agents.py
cd examples/00_hello/build
opencode run --agent primary "Hi, I'm Dana"

Basics¶

Example	What it demonstrates	Learn it in
`00_hello`	The minimum: one agent defined, compiled, and invoked via opencode	Your first agent
`10_multi_provider`	One agent compiled as three variants against different providers/models side by side	Agent model

Improvement loop¶

Example	What it demonstrates	Learn it in
`20_optimization_run`	A deliberately weak agent improved via `oac improve`, with a stronger model as optimizer	Improvement loop
`25_per_model_optimization`	Independent winners per model class — separate optimized prompts for fast / analytical / local	Improvement loop
`26_promote_and_reload`	Closing the loop: a promoted snapshot merges onto the baseline on the next compile	Improvement loop
`27_composable_improvements`	Agent prompt, skill, and tool each independently promoted, all merged at register time	Improvement loop

Prompt assembly & long-running work¶

Example	What it demonstrates	Learn it in
`28_context_blocks`	Volatility-tagged `ContextBlock`s + `PromptAssembler` for cache-friendly prompt composition	Agent model
`29_long_running_task`	The `TaskHandle` return shape for tools that may take minutes	Tools guide

Tools, resources, MCP, dispatch¶

Example	What it demonstrates	Learn it in
`30_tools`	One ScriptTool compiled in `bash`, `json`, and `both` tool formats — what each puts in the frontmatter	Tools guide
`31_spawn_agent`	`SpawnAgentTool` — typed agent-to-agent composition through a tool call	Tools guide
`32_multi_turn_mocks`	Multi-turn `AgentTest` with sequenced `MockResponse`s for monitoring-style scenarios	Testing guide
`33_sqlite_resources`	ScriptTool `execute(input, resources)` with an `AccessProfile`-bound SQLite database	Tools guide
`34_mcp_per_agent`	Two agents declaring different MCP server subsets in one compile	Tools guide
`35_fastapi_dispatch`	FastAPI dispatch: sync / async / fire-and-forget modes, variant routing, retry with fallback chains	Execution tiers
`36_mcp_server`	Compiled agents exposed as MCP tools alongside the FastAPI REST API	Project scaffolding

Multi-agent structure¶

Example	What it demonstrates	Learn it in
`40_subagents`	An orchestrator delegating to two Task-tool subagents	Agent model
`50_primary_dispatch`	Primary-to-primary spawning via the bundled `opencode_manager.py` bash dispatcher (fresh sessions, not Task)	Execution tiers
`60_workflow_agent`	The full workflow grammar in one agent: numbered steps, criteria, gates, routes, todo tracking	Agent model

Testing¶

Example	What it demonstrates	Learn it in
`70_oac_test`	`oac test` end to end: capability + tool tests, mock profiles, JSONL artifacts, incremental green-hash skip	Testing guide

Other runtimes (dialects)¶

Example	What it demonstrates	Learn it in
`80_pi_agents`	The same orchestrator + subagents tree compiled for opencode and pi (`build_both.py`)	Dialects
`81_pi_exploration`	Delegating to pi's built-in Explore agent via the `Agent()` tool	Dialects
`85_matrix_live_chat`	Capstone: one tree → 2 harnesses × 2 models, per-target autoloops (incl. the interactive tier, LLM-judged), per-target promotion, and one live chat dispatching any compiled variant	Optimization targets

Scaffolds¶

Example	What it demonstrates	Learn it in
`90_init_scaffold`	Three `oac init` template shapes (barebones / web / full) generated side by side for browsing	Project scaffolding
`91_saas_personalized`	The `saas-personalized` template: per-client intake → personalize → serve, pre-wired to per-client auto-optimization	Project scaffolding

examples/_shared/ holds helpers reused across examples (not a lesson in itself).

Suggested path¶

00_hello → first agent
30_tools + 33_sqlite_resources → tools
70_oac_test + 32_multi_turn_mocks → testing
20–27 → improvement loop
40/50/60 for structure, 80/81 when you need a second runtime
90/91 when you're ready to scaffold a real project