VoiceThere

Agent logs

VoiceThere stores structured log lines from your agent bundle — emitted via agentLog or overridden console.debug|log|info|warn|error in @voicethere/agent. Lines appear in the project dashboard (Project → Agent logs), on each session detail page, and via the CLI voicethere projects logs list.

Emitting logs from your agent

Prefer agentLog for structured fields you want to search later. Plain console calls are captured with a default message and optional structured payload when you pass objects.

import { agentLog } from "@voicethere/agent";

agentLog("peer joined", {
  level: "info",
  fields: { peerId: "client-1", room: "lobby" },
});

// console.* is also captured (level maps 1:1)
console.warn("inventory low", { sku: "potion", count: 2 });

Log levels

Supported levels (same in agent protocol and dashboard filters):

debug, info, warn, error

Dashboard

  • Project → Agent logs — newest project-wide lines with search, level filter, and optional JSON field filters (dot paths such as peerId).
  • Session detail → Logs — same controls scoped to one session; open a session from the logs table or the sessions list.
  • Each row shows timestamp, level, message, and expandable fields JSON.

Plan limits

Log storage is rolling — when you exceed your plan cap, the oldest lines are removed and the newest are kept. Limits depend on your project subscription (see the cap hint on the dashboard and the plans comparison table):

  • Maximum stored lines per project
  • Maximum stored lines per session
  • Lines per second (excess lines are dropped)
  • Retention in days

CLI

List logs for a project or filter to one session:

voicethere projects logs list --project <project-id>
voicethere projects logs list --project <project-id> --session <orchestrator-session-id>
voicethere projects logs list --project <project-id> --q "peer joined" --level info

API

Same filters as the dashboard — see Control plane API:

  • GET /api/v1/projects/:projectId/logs
  • GET /api/v1/projects/:projectId/sessions/:sessionId/logs

Query parameters: q, level, limit, fieldPath, fieldValue.

Session errors vs agent logs

Session errors are structured failure records (crashes, handler failures, provisioning issues) with stable error codes and data-channel events. Agent logs are general-purpose diagnostic lines you emit during normal operation — use both when debugging.

← All documentation