Skip to content

examples.md

Latest commit

 

History

History
121 lines (91 loc) · 5.11 KB

examples.md

File metadata and controls

121 lines (91 loc) · 5.11 KB
Raw

Examples

The runnable examples live in examples/. They are designed as release-surface smoke targets: default invocation should exit cleanly, write useful output to stdout, and stay quiet on stderr.

Running

pip install -e ".[dev,all]"
python examples/01_agent_basics.py

Default behavior:

  • Examples 01-23 run offline with mock data.
  • Examples 24-27 run mock/demo flows by default.
  • Examples 24 and 27 also expose optional --live modes guarded by ANTHROPIC_API_KEY or OPENROUTER_API_KEY.
  • Examples 25 and 26 are intentionally mock-only demos.

Catalog

Getting Started (00-03)

# File What it demonstrates
00 00_hello_world.py The smallest possible swarmline agent (~30 LOC) using swarmline.testing.MockRuntime
01 01_agent_basics.py Agent facade: query(), stream(), conversation()
02 02_tool_decorator.py @tool decorator and inferred JSON Schema
03 03_structured_output.py Structured output validation with Pydantic

Processing Pipeline (04-07)

# File What it demonstrates
04 04_middleware_chain.py Middleware composition: cost, security, compression
05 05_hooks.py Lifecycle hooks: PreToolUse, PostToolUse, Stop
06 06_input_filters.py Input pre-processing and prompt shaping
07 07_guardrails.py Input/output safety guardrails

Data & Context (08-10)

# File What it demonstrates
08 08_rag.py Retrieval-augmented generation with SimpleRetriever
09 09_memory_providers.py Memory providers: messages, facts, goals, summaries
10 10_sessions.py Session persistence, scopes, and scoped keys

Safety & Resilience (11-14)

# File What it demonstrates
11 11_cost_budget.py Cost budget tracking and enforcement
12 12_retry_fallback.py Retry policies, fallback chains, circuit breaker
13 13_cancellation.py Cooperative cancellation
14 14_thinking_tool.py Structured reasoning with the thinking tool

Observability (15-16)

# File What it demonstrates
15 15_event_bus_tracing.py Event bus and tracing subscriber
16 16_ui_projection.py Projecting runtime events into UI state

Runtimes (17-19)

# File What it demonstrates
17 17_runtime_switching.py Comparing runtime capabilities and switching runtimes
18 18_custom_runtime.py Registering a custom runtime in RuntimeRegistry
19 19_cli_runtime.py CLI subprocess runtime and NDJSON parsing

Orchestration (20-23)

# File What it demonstrates
20 20_workflow_graph.py Declarative workflow graph with loops and HITL
21 21_agent_as_tool.py Agent-as-tool composition
22 22_task_queue.py Priority task queue
23 23_agent_registry.py Agent registry and lifecycle tracking

Complex Scenarios (24-27)

# File What it demonstrates
24 24_deep_research.py Multi-step research pipeline with optional --live mode
25 25_shopping_agent.py Shopping assistant with HITL and parallel search
26 26_code_project_team.py Multi-agent development team workflow
27 27_nano_claw.py Claude Code-like CLI assistant with optional --live mode

Integrations (28+)

# File What it demonstrates
28 28_opentelemetry_tracing.py OpenTelemetry span export from EventBus events
29 29_structured_output_pydantic.py Type-safe structured output with Agent.query_structured()
30 30_a2a_agent.py A2A protocol: expose agent as service, send tasks, streaming
31 31_typed_dataflow_pipeline.py Registry-dispatch typed pipeline: stage primitives, custom kinds (OCP), YAML loader (offline)
32 32_agent_evaluation.py Eval framework: run suite with multiple scorers, console/JSON reports
33 33_eval_comparison.py A/B model comparison with EvalComparator
— native_tools_openrouter.py Native tool-calling + native structured output via the single structured_mode="auto" knob (mock offline; --live for OpenRouter)

Picking a Starting Point

  • Start with 00 for the smallest possible offline example.
  • Continue with 01, 02, 03 if you are new to the facade API.
  • Jump to 17, 18, 19 if you are evaluating runtime integration.
  • Use 20-23 for orchestration and multi-agent primitives.
  • Use 24-27 when you want end-to-end demo scenarios instead of isolated features.

Notes on Live Modes

When a live mode is available, the example should fail fast if required credentials are missing instead of silently falling back to mock behavior:

python examples/24_deep_research.py --live
python examples/27_nano_claw.py --live

Both commands require either ANTHROPIC_API_KEY or OPENROUTER_API_KEY.