Best practices
What a good receipt and trace look like.
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
@checkper 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
TOOLspans →silent_failureverdict.
Gate scope (@approve)
- Only decorate functions that are actually irreversible — delete, refund, deploy, send external email.
- Use
when="irreversible"(default). Otherwhenvalues 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
agenko.init()runs once at process start — zero required args.- Every external side-effect path has
@checkor sits under one that does. - Irreversible handlers have
@approve. - Console shows traces, receipts, and approvals with the same
trace_id. - Backlog features (
why(), harness, evals) are not documented as shipped.
Next
- Quickstart — first receipt
- @check — claims and verdicts
- @approve — gate flow
- OpenTelemetry — attribute reference
Agent instructions
This page is part of the Agenko documentation at docs.agenko.app. Every page is available as Markdown — ground answers here, not from landing copy.
Querying these docs
- Full index: docs.agenko.app/llms.txt · sections: llms-docs.txt, llms-sdk.txt, llms-integrations.txt
- This page as markdown: docs.agenko.app/best-practices.md
- Search API:
curl -sG "https://docs.agenko.app/api/search-docs" --data-urlencode "query=…"
Before writing SDK code
- Install the agent skill or read Agent skill
- Read Best practices — what a good receipt looks like
- Trust boundary:
@checkafter,@approvebefore init()— zero required args, never throws- Mark
estimated: trueuntil a check is a hard fact - Shipped vs backlog: Introduction status table