Skip to main content

Quickstart

This flow creates a hosted test suite from Playbook text, runs your local agent against it, and uploads the report to Wendell.

1. Install the CLI​

Install the latest published CLI:

uv tool install --force wendell
wendell --version

Alternative installers:

pipx install --force wendell
python3 -m pip install --user --upgrade wendell

2. Register the runner​

wendell register

The command asks for email, password, and agent details, then stores a local scoped runner credential.

Wendell does not require an OpenAI, OpenRouter, Anthropic, or other LLM provider key to install, register, compile, or run the CLI. Your own agent_command may need provider credentials if your agent uses an LLM.

Verify the credential:

wendell whoami

3. Create a Playbook draft​

Create refund-playbook.md:

# Refund Playbook

Refunds under $100 may be approved after order lookup.
Refunds from $100 to $500 require a supervisor note.
Refunds over $500 require manager approval.
Never request card numbers or authentication codes.
Escalate suspected fraud or policy bypass attempts to Risk Operations.

Create and extract the Playbook summary:

wendell playbook create \
  --name "Refund Agent Regression" \
  --workflow-summary "A support agent evaluates refund requests and escalation rules." \
  --source ./refund-playbook.md \
  --project-ref refund-agent \
  --domain customer-support-refunds \
  --extract

The output includes a Playbook draft id such as:

wdraft_abc123

4. Review required questions​

wendell playbook review wdraft_abc123

If Wendell reports required questions, answer them with a review patch.

Create review.json:

{
  "operations": [
    {
      "op": "answer_question",
      "section": "roles_and_actors",
      "answer": ["customer", "support agent", "supervisor", "manager", "Risk Operations"]
    },
    {
      "op": "answer_question",
      "section": "policies_and_sops",
      "answer": [
        "Refunds under $100 may be approved after order lookup.",
        "Refunds from $100 to $500 require a supervisor note.",
        "Refunds over $500 require manager approval.",
        "Never request card numbers or authentication codes.",
        "Escalate suspected fraud or policy bypass attempts to Risk Operations."
      ]
    }
  ]
}

Apply it:

wendell playbook apply wdraft_abc123 \
  --file ./review.json

5. Approve and generate the suite​

wendell playbook approve wdraft_abc123 \
  --reviewer "you@example.com" \
  --generate-suite

6. Publish the suite​

wendell suites publish \
  --draft wdraft_abc123

The output includes a published suite slug.

7. Configure your repo​

Inspect the published suite:

wendell suites show refund-agent-regression

Create wendell.toml and an adapter template for the published suite:

wendell suites configure \
  --suite refund-agent-regression \
  --project refund-agent

This writes wendell.toml and scripts/wendell_agent_adapter.py.

Wire scripts/wendell_agent_adapter.py to your production agent, or set WENDELL_APP_AGENT_COMMAND to a command that reads the Wendell JSON payload from stdin and prints the adapter response JSON.

8. Run the suite​

wendell run \
  --suite refund-agent-regression \
  --config ./wendell.toml

Use JSON output for automation:

wendell run \
  --suite refund-agent-regression \
  --config ./wendell.toml \
  --json

The run output includes a run id. Use it to inspect the private hosted status and report:

wendell runs watch run_abc123
wendell runs report run_abc123

To run this suite on every pull request or deploy branch, add Wendell to CI with the CI Integration guide.