Observability
Trace Groups
Group related runs with trace metadata.
Trace metadata lets observers group related agent runs by user, session, workflow, or product surface.
1. Add a Trace Name
const response = await agent
.prompt("Summarize this ticket.")
.withTrace({
name: "ticket-summary",
})
.send();Use stable names such as support-chat, ticket-summary, or retrieval-answer.
2. Add User and Session IDs
const response = await agent
.prompt("Answer the user's support question.")
.withTrace({
name: "support-chat",
userId: user.id,
sessionId: conversation.id,
})
.send();Use the same sessionId for related turns in one conversation.
3. Add Metadata and Tags
const response = await agent
.prompt("Handle this ticket.")
.withTrace({
name: "ticket-triage",
metadata: {
ticketId: ticket.id,
plan: customer.plan,
},
tags: ["support", "triage"],
})
.send();Keep metadata useful and safe to store. Do not include secrets or sensitive prompt content unless your observability policy allows it.
4. Continue an Existing Trace
await agent
.prompt("Follow up on this ticket.")
.withTrace({
traceId: existingTraceId,
name: "ticket-follow-up",
})
.send();Observers can use traceId to attach new work to an existing trace.
5. Read Trace IDs From the Response
const response = await agent
.prompt("Summarize this ticket.")
.withTrace({ name: "ticket-summary" })
.send();
console.log(response.trace?.traceId);
console.log(response.trace?.observationId);Trace ids are present when an observer returns them.