docs(cookbook): instrument an existing app and verify it end to end

[abhijaisrivastava15]

What

A cookbook quickstart that takes an app with no tracing at all to a verified integration, and then proves it worked rather than asking the reader to eyeball the dashboard.

Today the closest thing we have is observe/troubleshooting/no-traces-appearing, which diagnoses a symptom. Nothing tells you your integration is correct: a trace that arrives looking fine can still be missing cost, sessions, users, or half its spans.

Page added

• src/pages/docs/cookbook/quickstart/instrument-and-verify.mdx
• src/lib/navigation.ts - one entry, first in Cookbooks > Quickstart > Observability, because the five siblings there all assume tracing already works

Asset added

• public/fi_verify.py (246 lines) - serves at docs.futureagi.com/fi_verify.py, which the Install section curls

It is in this PR rather than its own so the page never ships a live link to a 404. The page publishes the file's line count and sha256 (9b331742...) so a reader can prove their copy in one command.

The worked example

Chintan's note was that a cookbook is only finished when it shows an agent end to end. The page now does, on a repository nobody wrote for us.

openai/openai-agents-python, its examples/customer_service airline support agent: a triage agent, a handoff, two specialist agents and a local tool. It is a fair target because it has all four of the page's problems at once. It emits no trace we can read, one message fans out across four agents, main.py is an interactive REPL so there is no entry point that runs once, and it already carries a conversation id and a passenger context, so Step 3 has a real session and a real user rather than invented ones.

The six steps were then followed literally against it. No business logic edited, main.py imported not modified, one new file for the entry point the repository does not have.

  PASS  G1   preflight ok, delivery ok
  PASS  G2   project_name='support-agent-quickstart' project_type='observe'
  PASS  G3   13 spans, 1 trace(s), 1 root(s), 0 orphan(s)
  PASS  G4   3 LLM span(s), 0 untyped
  PASS  G5   prompt and completion on every LLM span
  PASS  G6   session.id=['conv_94ac3e74fcc4']
  PASS  G7   user.id=['acct_10427']
  PASS  G8   model on every LLM span
  PASS  G9   tokens and cost on LLM spans, rolled up onto the root; root cost=0.00108604
  PASS  G10  no credential in any span attribute

  Future AGI integrated
  GREEN LIGHT achieved

That is a real run against api.futureagi.com with a real model call, real tokens and a real cost, not a transcript written by hand.

Screenshots

Three, from that run, on the platform. Every one is the genuine surface with nothing reconstructed.

The trace list reads the root and nothing else, which is why Step 4 puts the totals there. Latency, tokens and status arrive on their own; cost and the model do not.

Inside a trace, the instrumentor typed the agents, the model calls and the handoff. faq_lookup_tool is a local function the instrumentor cannot see, so its TOOL span is the three lines from Step 4. The attributes panel is the same list Step 4 sends, read back off a real span.

Because session.id was set once at the edge, both turns group without either turn knowing about the other.

This supersedes the earlier note on this PR that said there was nothing to screenshot. That was true of the tutorial alone and stopped being true once the worked example gave us a real trace to point at.

Notebook

quickstart/instrument-and-verify.ipynb is now on cookbook/quickstart-notebooks in future-agi/cookbooks, the 22nd in that folder, and the page carries the Colab and GitHub badge row like its 21 siblings. Both badge URLs return 200.

This also supersedes the earlier note saying there would be no badge row.

Shape

Written to the section's own skeleton, checked against all 34 existing quickstarts rather than one of them:

• ## Install (28/34), ## Tutorial with <Steps>/<Step> (33/34), ## What you built with <Check> (34/34), ## Next steps with <CardGroup cols={4}> (33/34)
• <TLDR>, <Prerequisites>, the badge row (21/34), and the | Time | Difficulty | Package | table, all present
• Frontmatter is title + description only, as every sibling has

One deliberate deviation: <Tabs> for the two integration routes (Future AGI SDK and plain OpenTelemetry). distributed-tracing sets the precedent for tabs on a multi-variant page, and the alternative is two pages for one procedure.

Tested by an agent that had never seen it

A fresh agent was given the page URL, real keys and a sandbox, and told to reach GREEN LIGHT or stop honestly. It reached all ten gates on the first real run, in about seven minutes against the page's own estimate of twenty. It also reached green on the printed directory layout with no __init__.py files at all, which confirms the tree as printed is correct.

It found four things, all fixed in this branch:

The tabs are a trap for anything that flattens the page to text. Steps 2 to 4 present the two tracks as tab-switched UI, so flattened they concatenate with no marker: setup.py twice, futureagi_rollup.py twice, and futureagi_spans.py twice as structurally different files under the same name. Mixing them is a guaranteed ImportError. Our own "Copy page as Markdown for LLMs" button and the docs MCP server both invite exactly that flattening. Every listing now names its track on the first line, and one sentence up front says to pick one track and stay on it.

The worked example described its one new file without printing it. It is now printed in full, including the line that points the agents SDK at an OpenAI-compatible endpoint that is not OpenAI.

The install list omitted -openai-agents, which is the instrumentor the worked example installs.

An undocumented stderr line on every run (ai-evaluation is not installed, please install it to trace protect) now has one sentence saying it is the optional Protect package and affects no gate.

Checks run

• node scripts/audit-links.mjs - 0 broken nav links, 0 broken content links, in nav so not an orphan
• Renders 200 on a local dev server off this branch; TLDR, Prerequisites, Steps, Step, Check, Tabs, Note, Warning and CardGroup all render as components, none leak as text
• All three images serve 200 from the branch
• Both notebook badge URLs return 200
• The rendered page flattened to plain text keeps all six track markers, so the two tracks stay separable without the tab UI
• Zero em-dashes, zero HTML entities
• Every internal link target verified to exist on dev

Preview

npm run dev

http://localhost:4321/docs/cookbook/quickstart/instrument-and-verify

Follow-up, not in this PR

observe/troubleshooting/no-traces-appearing currently ends at "recheck the causes above in order". A one-line link out to this page would close that dead end. Kept separate to keep this diff to one page.