Observability & Tracing

Gain visibility into your agent's thought process, debug failures, and monitor costs in production.

Why Observability Matters#

Agents are "black boxes" by nature. Without tracing, you don't know if an agent failed because of a bad prompt, a tool error, or a hallucination. Akios provides built-in hooks to stream events to your favorite monitoring platforms.

Using the Logger Interface#

The SDK exposes a `Logger` interface. You can attach multiple loggers to an agent to capture lifecycle events.

logger.ts

import { Agent, ConsoleLogger } from '@akios/sdk'

const agent = new Agent({
  name: 'SupportBot',
  model: 'gpt-4o',
  // Default logger prints nicely formatted steps to stdout
  loggers: [new ConsoleLogger()]
})

Custom Tracing (OpenTelemetry)#

For production, you'll want to send traces to tools like Jaeger, Datadog, or LangSmith. Implement the `AgentLogger` interface.

Implement the Logger

otel-logger.ts

import { AgentLogger, AgentEvent } from '@akios/sdk'
import { trace } from '@opentelemetry/api'

export class OpenTelemetryLogger implements AgentLogger {
  log(event: AgentEvent) {
    const span = trace.getTracer('akios').startSpan(event.type)
    
    // Add attributes based on event data
    span.setAttribute('agent.name', event.agentName)
    if (event.type === 'tool_start') {
      span.setAttribute('tool.name', event.data.tool)
      span.setAttribute('tool.input', JSON.stringify(event.data.input))
    }
    
    if (event.error) {
      span.recordException(event.error)
      span.setStatus({ code: 2 }) // Error
    }

    span.end()
  }
}

Attach to Agent

main.ts

const agent = new Agent({
  name: 'ProductionBot',
  model: 'gpt-4o',
  loggers: [new OpenTelemetryLogger()]
})

Visualizing Thoughts#

Tracing isn't just for debugging—it's for understanding. A "thought trace" reveals the agent's reasoning chain.

[Thought]

User wants weather. I should use 'get_weather' tool.

[Action]

get_weather({ city: "Tokyo" })

[Observation]

"Sunny, 25°C"

[Answer]

It is currently sunny and 25°C in Tokyo.