Observability
Observer interfaces, trace options, generation/tool events, and score contracts.
Import from @anvia/core or @anvia/core/observability.
Trace Types
type AgentTraceInfo = {
traceId: string;
observationId: string;
};
type AgentTraceOptions = {
traceId?: string;
name?: string;
userId?: string;
sessionId?: string;
version?: string;
tags?: string[];
metadata?: JsonObject;
};Purpose: trace identity and metadata passed into runs.
Return behavior: trace info can appear on prompt responses and final stream events.
Notable errors: none directly.
Run Observer Types
type AgentRunStartArgs = {
prompt: Message;
history: Message[];
agentName?: string;
agentDescription?: string;
maxTurns: number;
trace?: AgentTraceOptions;
};
type AgentRunEndArgs = PromptResponse;
type AgentRunErrorArgs = { error: unknown; usage: Usage; messages: Message[] };
interface AgentRunObserver {
readonly trace?: AgentTraceInfo;
startGeneration?(args: AgentGenerationStartArgs): AgentGenerationObserver | Promise<AgentGenerationObserver>;
startTool?(args: AgentToolStartArgs): AgentToolObserver | Promise<AgentToolObserver>;
end?(args: AgentRunEndArgs): void | Promise<void>;
error?(args: AgentRunErrorArgs): void | Promise<void>;
}Purpose: observe one agent run.
Return behavior: created by AgentObserver.startRun(...).
Notable errors: observer errors are ignored unless failOnObserverError is enabled.
Generation and Tool Observer Types
type AgentGenerationStartArgs = { turn: number; request: CompletionRequest };
type AgentGenerationEndArgs<RawResponse = unknown> = {
response: CompletionResponse<RawResponse>;
firstDeltaMs?: number;
};
type AgentGenerationErrorArgs = { error: unknown };
interface AgentGenerationObserver {
end?(args: AgentGenerationEndArgs): void | Promise<void>;
error?(args: AgentGenerationErrorArgs): void | Promise<void>;
}
type AgentToolStartArgs = {
turn: number;
toolName: string;
toolCallId?: string;
internalCallId: string;
args: string;
};
type AgentToolEndArgs = AgentToolStartArgs & { result: string; skipped?: boolean };
type AgentToolErrorArgs = AgentToolStartArgs & { error: unknown };
interface AgentToolObserver {
end?(args: AgentToolEndArgs): void | Promise<void>;
error?(args: AgentToolErrorArgs): void | Promise<void>;
}Purpose: observe model calls and tool calls inside a run.
Return behavior: called by the agent runtime as events complete or fail.
Notable errors: observer errors follow the registration error policy.
AgentObserver and Registration
interface AgentObserver {
startRun(args: AgentRunStartArgs): AgentRunObserver | Promise<AgentRunObserver>;
score?(args: AgentScoreArgs): void | Promise<void>;
}
type AgentObserverRegistration = {
observer: AgentObserver;
failOnObserverError?: boolean;
};
type ObserveOptions = {
failOnObserverError?: boolean;
};
function createObserver(observer: AgentObserver): AgentObserver;Purpose: top-level observer plugin contract.
Return behavior: createObserver(...) returns the observer unchanged, mainly for typing.
Notable errors: score(...) can reject depending on the observer implementation.
AgentScoreArgs
type AgentScoreArgs = {
traceId?: string;
observationId?: string;
name: string;
value: number | string;
comment?: string;
metadata?: JsonObject;
};Purpose: submit evaluation or feedback scores for a trace or observation.
Return behavior: consumed by observers that implement score(...).
Notable errors: observers can require trace IDs or credentials.
For workflow guidance, see Tracing.