---
title: Best practices
description: What a good receipt and trace look like.
---

# Best practices

Read this before instrumenting an agent. A good Agenko run is one trace, one receipt per wrapped action, and honest `estimated` flags — not a forest of orphan spans or LLM-inferred "grounding."

## One execution, one trace

- Wrap **one agent run** in a root span (auto-instrumentation does this when you call `init()`).
- LLM calls, tool calls, and app logic are **child spans** — not separate traces.
- Attach `user_id`, `session_id`, and tags on the root when you have them — the console filters on these later.

## Name spans for debugging

Use stable names humans search for: `handle_ticket`, `create_issue`, `refund_payment` — not `step_3` or `agent_node`.

| Bad | Better |
|---|---|
| `process` | `support.handle_ticket` |
| `tool` | `github.create_issue` |
| `llm` | `gen_ai.completion` (OpenInference default) |

## Meaningful input and output

- **Input:** the ticket, user message, or args the action received.
- **Output:** the return value or exception — truncated in the receipt, full on the span when safe.
- Redact secrets at the app layer before they hit spans. Server-side masking is roadmap — do not log API keys today.

## Receipt scope (`@check`)

- One `@check` per **business action** you need to prove — not every helper.
- Set `claims=` to the tool or side-effect you expect (`github.create_issue`, `stripe.refund`).
- Silent failure = claimed tool never appeared in OpenInference `TOOL` spans → `silent_failure` verdict.

## Gate scope (`@approve`)

- Only decorate functions that are **actually irreversible** — delete, refund, deploy, send external email.
- Use `when="irreversible"` (default). Other `when` values pass through until policy ships.

## What makes a receipt trustworthy

| Signal | Rule |
|---|---|
| `verdict` | From measured facts — empty output, missing tool span, exception |
| `checks[]` | Score-shaped rows with `name`, `value`, `source` |
| `grounding_score` | Always `estimated: true` |
| LLM-as-judge | **Do not** put on the receipt — that is not a measurement |

## OTEL attributes

Prefer OpenInference + `agenko.*` from `agenko/spec/telemetry/semantic-conventions.yaml`. Dual-export to your existing collector is fine; do not register two competing global tracer providers.

## Checklist before production

1. `agenko.init()` runs once at process start — zero required args.
2. Every external side-effect path has `@check` or sits under one that does.
3. Irreversible handlers have `@approve`.
4. Console shows traces, receipts, and approvals with the same `trace_id`.
5. Backlog features (`why()`, harness, evals) are not documented as shipped.

## Next

- [Quickstart](/quickstart) — first receipt
- [@check](/check) — claims and verdicts
- [@approve](/approve) — gate flow
- [OpenTelemetry](/opentelemetry) — attribute reference

## Agent instructions

This page: https://docs.agenko.app/best-practices.md

Fetch `/llms.txt` for the full index. Search: `GET /api/search-docs?query=...`
