Docs menu

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.

BadBetter
processsupport.handle_ticket
toolgithub.create_issue
llmgen_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

SignalRule
verdictFrom measured facts — empty output, missing tool span, exception
checks[]Score-shaped rows with name, value, source
grounding_scoreAlways estimated: true
LLM-as-judgeDo 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

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

Before writing SDK code

  • Install the agent skill or read Agent skill
  • Read Best practices — what a good receipt looks like
  • Trust boundary: @check after, @approve before
  • init() — zero required args, never throws
  • Mark estimated: true until a check is a hard fact
  • Shipped vs backlog: Introduction status table

Page: Best practices
HTML: https://docs.agenko.app/best-practices
Markdown: https://docs.agenko.app/best-practices.md