Retrieval Tracing

Retrieval is one of the most important span types to record in Grounded because it explains what context the model had before it responded.

Use kind: 'retrieval'.

Example

const trace = tracing.startTrace({
  name: 'support.reply',
  sessionId: 'chat_123',
  userId: 'user_123',
  resource: { agentId: 'agt_123' },
});
 
const retrieval = trace.startSpan({
  name: 'policy.search',
  kind: 'retrieval',
  input: {
    query: 'refund policy timeline',
    source: 'faq-index',
    topK: 5,
  },
});
 
retrieval.end({
  status: 'ok',
  output: {
    documents: [
      { id: 'doc_1', score: 0.94, title: 'refund policy v3' },
      { id: 'doc_9', score: 0.81, title: 'refund exceptions' },
    ],
  },
});

What To Capture

• retrieval query
• source or index name
• top-k or candidate count
• stable document IDs
• scores or ranks
• short, safe summaries of the returned content

Why It Matters

When a trace becomes a session, retrieval spans give Grounded more context for:

• debugging failure modes
• evaluating grounding quality
• understanding whether the model lacked context or ignored it

Keep It Bounded

Do not dump entire documents into the trace unless you truly need them. Prefer:

• IDs
• scores
• excerpts
• metadata