> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unpod.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Harness

> Everything that runs around an agent in production - tools, retries, guardrails, human handoff, evals and observability.

The brain decides what to say. The harness is everything around it that
makes an agent safe to put in front of customers: the runtime that runs each
turn, the tools it calls, retries when a tool fails, guardrails on what it
may say, a handoff to a human when it should stop, evals that score it, and
the logs that show what happened. The runtime, tools, retries, `never_say`
guardrails and handoff run in real time on every call; evals score the call
after it ends.

## The primitives

| Primitive | What it is | Where it lives today |
| - | - | - |
| Runtime | Runs each turn: your brain, the speech pair, the call | Production - Agent Studio agents ([build one](https://docs.unpod.ai/playbook/build-an-agent.md)), or SDK agents via `client.agents.voice.create()` |
| Tools | HTTP calls the agent makes mid-conversation | Production - [playbook tools](https://docs.unpod.ai/superdialog/tools.md), or Agent Studio → Persona → Tools. MCP tools: in build |
| Retries | A capped retry, then a fallback route, when a tool fails | Production - `failed: {retry: N, on_exhaust: ...}` in a playbook pipeline |
| Guardrails | Hard limits on what the agent may say | Production - `never_say` and hard gates per [playbook](https://docs.unpod.ai/superdialog/playbooks.md) checkpoint. A policy layer: in build |
| Human handoff | Transfer to a person mid-call | Production - Agent Studio → Advanced → **Enable Handover** |
| Evals | Score a conversation against what good looks like | Production - the Realtime Evaluations toggle (scored after the call), [Playground Optimize](https://docs.unpod.ai/playbook/optimize.md), [`superdialog eval`](https://docs.unpod.ai/superdialog/evals) |
| Observability | What happened on every call | Production - call logs, recordings, transcripts and [analytics](https://docs.unpod.ai/speech-stack/analytics.md) |

Most of the harness is declared in the playbook:

```yaml playbook.yaml (excerpt) theme={null}
journeys:
  booking:
    checkpoints:
      - id: collect
        goal: "Have city and date"
        never_say: ["our systems are slow"]   # guardrail
        on_failure: booking.handoff            # route to the escalation checkpoint
      - id: confirm
        pipeline: confirm_and_hold
      - id: handoff
        terminal: true
        outcome: escalated

tools:
  - id: hold_slot                               # a tool
    type: http
    method: POST
    url: "{{ env.API_BASE_URL }}/slots/hold"

pipelines:
  - id: confirm_and_hold
    steps:
      - tool: hold_slot
        on:
          ok: continue
          failed: {retry: 2, on_exhaust: booking.collect}   # retry, then fall back
```

## Good to know

* **Two runtimes, two dial paths.** Agents built in Agent Studio are dialed
  with the [Task API](https://docs.unpod.ai/api/execution/task-make-call-overview.md). Agents
  created with the SDK are dialed with `client.calls.create()`. Do not mix
  them.
* **Handoff is a warm transfer** on Agent Studio agents: the caller hears
  hold music while the person hears an announcement. The transcript is not
  passed to the person.

## On the spine

The harness wraps every interaction. It reads context and the entity before
the first turn, and it records tool calls, handoffs and the evaluation score
on the interaction's outcome.

## What stays hidden

Prompt assembly, which provider served a turn, retry timers and failover.
You declare tools, gates and handoff numbers; the harness runs them.

## Status

**Production:** the runtime, HTTP tools, retries, `never_say` guardrails,
human handoff, evals, and call-level observability. **In build:** MCP tools,
and a policy layer for guardrails beyond the playbook.

## Go deeper

> **[Tools](https://docs.unpod.ai/superdialog/tools.md)**
>
> Declare HTTP and Python tools in a playbook.

> **[Playbooks](https://docs.unpod.ai/superdialog/playbooks.md)**
>
> Checkpoints, gates and `never_say`.

> **[Evals](https://docs.unpod.ai/superdialog/evals.md)**
>
> Score conversations before and after launch.

> **[Agents](https://docs.unpod.ai/core-engine/agent-workforce.md)**
>
> The workers the harness runs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.