# Examples

Find the right runnable workflow.

The examples live in the repository, not in the PyPI package. Clone it once, let uv build the environment, and run each example as a module from the repository root:

~~~bash
git clone https://github.com/datagol/agent-harness-x.git
cd agent-harness-x
uv sync --all-extras
uv run python -m examples.skills_demo
~~~

Do not append `.py` to a module name. Most examples import small shared helpers from the `examples` package (`_console`, `_calculator`, `_fixtures`, `_decision_fixtures`), so run them from the checkout rather than copying a single file. `prompt_caching`, `flight_recorder`, and `postgres_runtime` are self-contained and can be copied anywhere `harnessx` is installed.

## Start without external services

~~~bash
uv run python -m examples.skills_demo
uv run python -m examples.prompt_caching
uv run python -m examples.runtime_approvals
uv run python -m examples.flight_recorder --output incident.hx
uv run python -m examples.jev_routing --min-confidence 0.8
uv run python -m examples.jev_classification
uv run python -m examples.jev_answer_review
~~~

These use scripted model responses while exercising the real engine, runtime, and recorder. The recorder output path must not already exist. The Jev examples use fixed decision fixtures; changing their input does not change the fixed offline decision.

## Every example

| Entry point | What it demonstrates | Requirements |
| --- | --- | --- |
| `examples.simple_chat` | The smallest live agent: streaming chat, a calculator tool, read-only workspace tools bounded to the current directory, and a `usage` command | Anthropic key |
| `examples.provider_chat --provider P --model M` | The same calculator agent across Anthropic, OpenAI, Gemini, OpenRouter, and Azure OpenAI, streaming or ordinary runs, with usage and cache counters | The provider's extra and key |
| `examples.prompt_caching` | A two-step loop with a stable prompt prefix: the prefix key of each model request, the cache hint a provider receives, and cache write and read counters. `--off` disables caching, `--live` uses a real model | No services by default |
| `examples.coding_agent` | A coding assistant with file and shell tools bounded to the working directory, an audit middleware, and terminal approvals for writes and commands | Anthropic key |
| `examples.memory_agent` | Two persistent memories as tools: markdown notes and structured long-term facts under `.agent_memory/` | Anthropic key |
| `examples.multi_agent` | Specialists declared in the constructor with their own tools and permissions; the orchestrator delegates isolated tasks | Anthropic key; URL research asks for approval |
| `examples.skills_agent` | Lazy skill loading in a live conversation, with a hook that shows when a skill is invoked. `AGENT_PROVIDER` and `AGENT_MODEL` select the model | Anthropic key by default |
| `examples.skills_demo` | Skill discovery, invocation, and hook ordering with a scripted model | No services |
| `examples.knowledge_agent` | Answers from an Open Knowledge Format bundle with `search_concepts`, `read_concept`, and `get_neighbors`, and a hook showing each access. `AGENT_KNOWLEDGE` points at another folder or git URL | Anthropic key by default |
| `examples.runtime_approvals` | A tool that requires approval, persisted on SQLite, then approved or declined with `approve(pending, resume=True)`, which finishes the run | No services; terminal input |
| `examples.flight_recorder --output incident.hx` | A model call that fails and is retried, middleware boundaries, an exported incident bundle, and playback with zero model or tool calls | No services; the output path must not exist |
| `examples.sandboxed_coder` | Python execution under process CPU, memory, and time limits, with SQLite checkpoints | Anthropic key; POSIX host |
| `examples.postgres_runtime` | Live streaming on the PostgreSQL runtime | `postgres` extra, `DATABASE_URL` or `--config PATH`, Anthropic key |
| `examples.postgres_runtime check` / `crash` / `status` / `resume` | Storage check, a written report, a hard process exit, and recovery of the same run without repeating the tool | `postgres` extra and a database; no model key |
| `examples.jev_routing --min-confidence 0.8` | A Choice decision selects one agent factory; unknown, uncertain, or unavailable decisions fall back to a general agent | No services by default; `--live` needs the `jev` extra |
| `examples.jev_classification` | A Choice decision classifies a document as W2, Deposit, Insurance, Payroll, or unknown | No services by default |
| `examples.jev_answer_review` | After a completed run, Score reviews coverage and Noul assesses evidence support | No services by default |
| `examples.langsmith_tracing` | LangSmith lifecycle tracing on a parent agent with a nested specialist span | `langsmith` extra, Anthropic and LangSmith keys |
| `examples.run_evals --offline` | Three scripted evaluations through the evaluation library; drop `--offline` for a live model and uploads | `langsmith` extra |
| `examples.mcp_agent --server NAME --command CMD` | Tools from an MCP server alongside native tools, over stdio or SSE | `mcp` extra, an installed MCP server, Anthropic key |

Run each with `uv run python -m`.

For the PostgreSQL crash scenario, follow the [durability walkthrough](../postgres-durability/). The browser launch still runs the live streaming example; the recovery walkthrough uses separate terminal commands.

## Select a provider

~~~bash
uv run python -m examples.provider_chat \
  --provider openai \
  --model YOUR_MODEL_ID \
  --prompt "What is 40 * 10?"
~~~

Use `--no-stream` for ordinary results, and `usage` in the interactive chat to print token and cache counters. On Azure, `--model` is the deployment name. Most other live examples select Anthropic unless their configuration is edited.

## Run evaluations

~~~bash
uv run python -m examples.run_evals --offline
~~~

The example's offline mode uses scripted responses. In the evaluation library itself, `offline=True` disables upload but does not prevent your agent from making live model calls. See [Tracing & evaluations](../evaluations/).

## Run live Jev decisions

~~~bash
export TYPESAFE_API_KEY='your-key'
uv run python -m examples.jev_classification --live --text 'Document text here'
uv run python -m examples.jev_answer_review --live
uv run python -m examples.jev_routing --live --min-confidence 0.8 \
  --provider anthropic --model YOUR_MODEL_ID
~~~

Live routing also needs the selected generative provider's credentials and extra. Its confidence threshold is required; `0.8` illustrates caller configuration and is not a calibrated default. Live answer review sends a fixed agent answer and evidence to Jev, then reports Score and Noul results separately from the agent run.

See [Decisions with Jev](../decisions/) for the typed API, failure behavior, and lifecycle. The harness-web entries for these three examples remain offline demos.

## Launch from a browser

[harness-web](../web-demo/) exposes every entry point above in an example library, along with input, approvals, stream output, and downloads. General chat is separate and supports editable prompts, uploaded skills, and MCP setup.