Choose and run examples

The examples progress from basic calls through control flows and Agent capabilities to complete execution patterns. Each directory describes inputs, dependencies, commands, artifacts, failures and validation. Third-party tools and database adapters live in _shared/tools, outside framework dependencies.

1. Download consumer examples

The documentation build produces ditto-examples.zip. Extract it, read its README and run npm install. It installs Ditto from npm without framework source or path aliases.

unzip ditto-examples.zip -d ditto-examples
cd ditto-examples
npm install
node examples/package-basics/context.ts 'Hello Ditto'
node examples/package-basics/tools.ts 'A😀'

For model-backed tasks, copy examples/package-basics/.env.example to .env and configure the model and Redis. Follow each example README for database, browser, OCR, audio and MCP dependencies. The archive excludes secrets, node_modules, databases, test artifacts and framework source.

The repository's npm run build compiles the framework. The consumer archive has no framework build step and strips it from example scripts. Maintainer check:*:package commands require the source checkout and are not consumer commands.

2. Start small

Example	Dependencies	Result
Context	Main package	Actual LOAD → SELECT output
Tool	Main package	Character count and Observation
Conversation Agent	Model, Redis, file SQLite	Persistent conversation, recovery, replay and answer file
Optional retrieval	Main and retrieval packages	Candidates and sources
Integrations and extensions	Per example	Custom Worker, Skill, Memory ranking and real MCP

3. Seven control-flow groups

Sequence, conditions/routing, parallelism/aggregation, iteration, recovery, human control and lifecycle.

Choose the control structure, then its Nodes; each business flow does not need a new framework API. The public-call boundary maps 38 examples to public Nodes.

4. Twelve capability groups

The capability index covers request understanding, planning, retrieval, analysis, context, memory, system operations, result interpretation, content, multimodal understanding, data/code, and validation/safety.

Choose the business entry point and read its _shared/tools adapters. Context uses Redis and Memory uses persistent storage; business systems still need independent state checks. The capability composition reference maps 86 entry points to APIs.

5. Sixteen complete execution patterns

Pattern	Prerequisites	Complete chain
4.1 RAG	Context, Memory, retrieval	Question to cited answer
4.2 Web Q&A	Tools, page reading	Search, read, filter and cite
4.3 Deep research	Loop, budgets	Subquestions, repeated search, gaps and report
4.4 ReAct	INFER actions, Tool/MCP	Decide, act and observe until stopping
4.5 Plan-and-Execute	Graph dependencies, dynamic Loop	Plan, execute and replan
4.6 Reflection	Checks, versions	Generate, critique, revise and recheck
4.7 Candidate selection	Parallelism, deliberation	Generate, evaluate, choose or combine
4.8 Tool chain	Tools, side effects	Customer/order lookup, update and notify
4.9 Human-in-the-loop	Persistence, trusted approval	Stage output, human edit and continuation
4.10 Multi-Agent	Role context, parallelism	Assign, execute, collect and aggregate
4.11 Supervisor	Review, budgets, reassignment	Supervisor review and further delegation
4.12 Handoff	Atomic responsibility state	Transfer ownership, acknowledge and recover
4.13 Specialist routing	Conditions, permissions	Classify domain and constrain execution
4.14 Debate	Independent context, sources	Agreement, disagreements and synthesis
4.15 Auto-repair	Actual execution feedback	Error, change and rerun validation
4.16 Long-running recovery	Checkpoints, business idempotency	Interrupt, reconcile, resume and deliver

6. Reuse an example

Copy the pattern directory and its relative _shared application imports, preserving layout. Replace identity, sources, tools, output sinks and configuration; retain stage contracts, validation and recovery rules.

Copying only cli.ts is usually insufficient. The archive preserves paths so you can run it before removing unused parts. Functions such as runRag are application entry points, not framework npm exports.

7. Verify actual completion

Record the real environment, model, storage and external systems. Check final files/database/remote state. Test new tasks, replay, errors, cancellation, unavailable services and process recovery separately. TypeScript success or a model response alone does not establish end-to-end task success.