Tracing & Error Handling
Inspect execution telemetry and handle runtime faults safely.
Integrations & Observability
Observability features provide deep visibility into every tool call, turn latency, state transition, and token count using Tracer.
Attaching a Telemetry Tracer
import { AgentBuilder, OpenAIAdapter, Tracer } from 'Weave';
const tracer = new Tracer({
serviceName: 'agent-service',
logLevel: 'info',
onSpanEnd(span) {
console.log(`[Span]: ${span.name} | Duration: ${span.durationMs}ms | Status: ${span.status}`);
},
});
const adapter = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY!, model: 'gpt-4o' });
const agent = new AgentBuilder()
.name('ObservedAgent')
.llm(adapter)
.tracer(tracer)
.build();
async function run() {
const result = await agent.run('Run diagnostic telemetry audit');
const trace = tracer.exportTrace(result.runId);
console.log(`Trace Duration: ${trace.totalDurationMs}ms (${trace.spans.length} spans)`);
}
run().catch(console.error);OpenTelemetry Collector Export
Export traces directly to OTLP collectors (Datadog, Honeycomb, New Relic):
const otelTracer = new Tracer({
exporter: {
type: 'otlp-http',
endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
},
});Error Handling & Taxonomy
Weave provides a structured, strongly typed error hierarchy allowing developers to catch, inspect, and recover gracefully from tool execution failures, schema mismatches, and security policy violations.
Error Hierarchy Overview
All SDK exceptions inherit from AgentError:
AgentError (Base SDK Error)
├── ToolError
│ ├── ValidationError (Zod schema mismatch)
│ ├── ExecutionError (Unhandled exception inside tool)
│ └── TimeoutError (Tool execution exceeded threshold)
├── StructuredOutputError (JSON output schema validation failure)
├── GuardrailValidationError (Input/Output security policy violation)
├── HandoffError (Multi-agent routing or max depth error)
└── ProviderAdapterError (LLM API key or network failure)Error Classes & Attributes
Prop
Type
Code Example: Graceful Catch & Recovery
Inspect and handle specific error codes during agent runs:
import {
AgentBuilder,
OpenAIAdapter,
ToolError,
ValidationError,
StructuredOutputError,
} from 'Weave';
const adapter = new OpenAIAdapter({
apiKey: process.env.OPENAI_API_KEY!,
model: 'gpt-4o',
});
const agent = new AgentBuilder().llm(adapter).build();
async function runSafely() {
try {
const result = await agent.run('Execute processing pipeline...');
console.log(result.output);
} catch (err: any) {
if (err instanceof ValidationError) {
console.error(`[Schema Invalid]: Tool ${err.toolName} received invalid arguments.`, err.issues);
} else if (err instanceof ToolError) {
console.error(`[Tool Failure]: Tool ${err.toolName} failed with code: ${err.code}`);
} else if (err instanceof StructuredOutputError) {
console.error(`[Structured Output Error]: Unrepairable output: ${err.rawOutput}`);
} else {
console.error(`[Unhandled SDK Error]: ${err.message}`);
}
}
}
runSafely().catch(console.error);