Learning Paths
Add Observability
Observe agent runs, model generations, tool calls, usage, and traces.
Use this path when you need to inspect what happened during an agent run.
Goal
By the end, you should know how to observe:
- prompt run start and end
- model generation requests and responses
- tool calls and tool results
- usage data
- trace metadata
Path
- Read Observers to attach runtime observers.
- Read Trace Groups to group related work.
- Read Tracing for trace metadata and integrations.
- Read Langfuse to send Anvia traces to Langfuse.
- Read Streaming Events if your UI needs live events.
- Read Prompt Responses to understand response usage and trace fields.
What To Log First
Start with:
- agent id
- prompt run id or conversation id
- model name
- total tokens
- tool names called
- error type and message
- trace id when available
Do not log sensitive prompt, document, or tool data unless your product policy allows it.
Minimal Observer Shape
Observers are plain TypeScript interfaces, so object literals work. For app code, prefer a class when the observer will keep state, share configuration, or be reused across agents.
import { AgentBuilder, type AgentObserver, type AgentRunObserver, type AgentRunStartArgs } from "@anvia/core";
import { OpenAIClient } from "@anvia/openai";
class ConsoleObserver implements AgentObserver {
startRun(args: AgentRunStartArgs): AgentRunObserver {
console.log("run_start", {
prompt: args.prompt.role,
maxTurns: args.maxTurns,
trace: args.trace,
});
return {
startGeneration({ turn, request }) {
console.log("generation_start", {
turn,
tools: request.tools.map((tool) => tool.name),
});
return {
end({ response }) {
console.log("generation_end", response.usage.totalTokens);
},
};
},
startTool({ toolName }) {
console.log("tool_start", toolName);
return {
end({ result, skipped }) {
console.log("tool_end", { skipped, result });
},
};
},
end({ usage }) {
console.log("run_end", usage.totalTokens);
},
error({ error }) {
console.error("run_error", error);
},
};
}
}
const model = new OpenAIClient({ apiKey }).completionModel("gpt-5");
const observer = new ConsoleObserver();
const agent = new AgentBuilder("support", model)
.instructions("Answer support questions clearly.")
.observe(observer)
.build();
const response = await agent
.prompt("How do I reset my password?")
.withTrace({
name: "support-question",
userId: "user_123",
metadata: { surface: "docs-example" },
})
.send();
console.log(response.trace);Add Next
| Need | Read |
|---|---|
| Send traces to Langfuse | Langfuse |
| Stream to a UI | Readable Streams |
| Debug tool loops | Turn Limits and Cancellation |
| Production checklist | Prepare for Production |