exagent

# Diagnose an integration

Start with the boundary that failed: construction, model admission, tool
validation, effect execution, persistence or export. Retain the known progress
without turning uncertainty into permission to repeat work.

## Common symptoms

| Symptom | Inspect | Next action |
|---|---|---|
| A provider resolves but tools/streaming are rejected | Model protocol, capabilities and explicit profile. | Configure the [qualified profile](models-and-limits.md); catalogue membership is insufficient. |
| `invalid_tool_arguments` before invocation | Final arguments envelope, strict JSON, schema and stock diagnostics. | Fix the producer/profile. Preserve the argument gate; do not strip evidence or repair JSON. |
| Output validation fails | Ecto changeset, output mode and remaining request budget. | Fix the output contract or input. Deliver only the successful terminal output. |
| Server returns `:busy` / `:queue_full` | Active run, pending count and byte bounds via `Server.health/1`. | Apply application backpressure; queue admission is volatile. |
| An event appears on the wrong screen | Namespace and request ID in `ExAgent.Event`. | Subscribe to the authenticated topic and match both identifiers. |
| A checkpoint fails | `CheckpointError` and current dirty state. | Retry the exact storage transition, not the prompt or effect. |
| Restore rejects stored data | Snapshot/record version, ID, policy and model/tool bindings. | Follow [migration](migration.md); do not silently replace it with an empty conversation. |
| A resumed attempt reports uncertainty or an active claim | Current continuation record and external effect evidence. | Recover/reconcile explicitly; do not start a competing fresh run. |
| MCP times out | Request deadline, pool capacity and remote outcome. | Treat the effect as potentially completed; reconnect never means replay. |
| Token/cost totals differ across parent and child spans | Inclusive totals, provenance and completeness. | Read the root once; do not add an inclusive parent to its children. |

## Langfuse or Opik shows empty input/output

With default content capture disabled, **Input `null` and Output `undefined` are
expected**. They are not evidence that a model step did nothing. Use the
observation's attributes to inspect run/root/parent IDs, request/tool counters,
status, usage completeness, provenance and estimated cents.

TestModel tokens are synthetic, and estimated cost is not an invoice. A recovery
trace can retain an earlier error followed by a valid checkpoint/resume; inspect
the operation's place in the tree and its causal outcome. Historical error spans
are not erased by later success.

Read [Observability](observability.md) before enabling content capture or choosing an
export route. Content redaction occurs before transport; the host owns credentials,
SDK and exporter lifecycle.

## Distinguish test results

An excluded test never executed. Provider and SQL tests require their external
systems and explicit configuration. An executing test that reaches its timeout
fails. A passing TestModel test establishes local behavior, not provider
compatibility. Use [Testing](testing.md) to select the relevant boundary.

## Report a reproducible problem

Include the package/source version, Elixir/OTP, model/transport profile, a minimal
public-API example, the sanitized reason and the relevant partial counters/status.
Use TestModel when the issue can be reproduced locally. Include real-backend
evidence separately when the failure depends on that backend.

Do not attach a whole live result, error, `.env`, credential-bearing model or
unredacted trace payload. Application data can contain secrets even when it is
valid JSON.

API: `ExAgent.RunError`,
`ExAgent.Server.health/1`,
`ExAgent.Continuation`.