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:

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

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. The browser launch still runs the live streaming example; the recovery walkthrough uses separate terminal commands.

Select a provider

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

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.

Run live Jev decisions

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 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 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.