Dashboard DevTools

Déboguez et tracez vos agents en temps réel

Un dashboard HTTP + WebSocket local qui affiche chaque appel d'outil, token LLM, décision d'agent et latence — en direct, dans votre navigateur. Aucun service externe, aucun fichier de config. Trois lignes pour démarrer.

Tracing Live

Chaque appel outil, token et étape agent visible en temps réel

Sessions

Groupez les runs en sessions pour voir tout le contexte conversationnel

ReplayDebugger

Rejouez des runs passés avec des inputs modifiés et comparez le diff

Mode Remote

Visualisez les traces de production depuis votre machine locale

APIs multiples

withTrace(), décorateur @Trace(), trace.start/end manuel

Imbrication

Workflows → agents → outils, rendu en arbre complet

Installation

npm install @orka-js/devtools

Démarrer en 3 lignes

Le navigateur s'ouvre automatiquement. Le dashboard est prêt. Commencez à tracer.

server.ts

import { devtools } from '@orka-js/devtools'
 
await devtools({ port: 3001 })
// Dashboard opens at http://localhost:3001

Wrapper votre agent

withTrace enveloppe n'importe quelle fonction. Chaque appel à tracedRun() apparaît dans le dashboard.

agent.ts

import { devtools, withTrace } from '@orka-js/devtools'
import { ReActAgent } from '@orka-js/agent'
import { OpenAIAdapter } from '@orka-js/openai'
 
await devtools({ port: 3001 })
 
const agent = new ReActAgent({
  goal: 'Help customers with their orders',
  tools: [getOrder, cancelOrder, refundOrder],
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
})
 
const tracedRun = withTrace(agent.run.bind(agent), {
  name: 'customer-support',
  type: 'agent',
})
 
// Every call appears in the dashboard
await tracedRun('What is the status of order #1234?')

Tracing inline avec trace.wrap

agent.ts

import { trace } from '@orka-js/devtools'
 
const result = await trace.wrap('agent', 'customer-support', () =>
  agent.run('Cancel my order #1234')
)

Décorateur de classe

agent.ts

import { Trace } from '@orka-js/devtools'
import { ReActAgent } from '@orka-js/agent'
 
class CustomerSupportAgent extends ReActAgent {
  @Trace({ type: 'agent', name: 'customer-support' })
  async run(input: string) {
    return super.run(input)
  }
}

Sessions

Groupez des runs liés — ex. tous les tours d'une seule conversation utilisateur.

conversation.ts

import { trace } from '@orka-js/devtools'
 
const sessionId = trace.session('conversation-user-42')
 
await trace.wrap('agent', 'turn-1', () => agent.run('Hello'))
await trace.wrap('agent', 'turn-2', () => agent.run('Cancel my order #1234'))
await trace.wrap('agent', 'turn-3', () => agent.run('What is my refund status?'))
 
trace.endSession(sessionId)
// All 3 runs are grouped under "conversation-user-42" in the dashboard

ReplayDebugger

Rejouez un run passé avec un prompt modifié et comparez le diff de sortie. Pas besoin de relancer tout le système.

replay.ts

import { devtools, createReplayDebugger } from '@orka-js/devtools'
 
const { tracer } = await devtools({ port: 3001 })
const debugger = createReplayDebugger(tracer)
 
// Replay a past run with a modified prompt
const comparison = await debugger.replayRun({
  runId: 'run-abc123',
  sessionId: 'session-xyz',
  modifyInput: (input) => ({
    ...input,
    prompt: 'Updated: always verify order exists before cancellation.',
  }),
})
 
console.log(comparison.diff)
// { original: '...', replayed: '...', changed: true }

Mode Remote (Production)

Envoyez les traces de votre agent en production vers un collecteur, puis visualisez-les depuis votre machine locale.

devtools.ts

// ── Production agent: send traces to collector ──
await devtools({
  source: 'remote',
  mode: 'agent',
  remote: {
    endpoint: 'https://traces.mycompany.com',
    apiKey: process.env.COLLECTOR_API_KEY,
    projectId: 'my-ai-app',
    environment: 'production',
    sampling: 0.1, // trace 10% of requests
  },
})
 
// ── Your machine: view production traces locally ──
await devtools({
  source: 'remote',
  mode: 'viewer',
  remote: {
    endpoint: 'https://traces.mycompany.com',
    apiKey: process.env.COLLECTOR_API_KEY,
    projectId: 'my-ai-app',
    filters: { environment: 'production', timeRange: 'last-1h' },
  },
  port: 3001,
})

Configuration

Option	Type	Default	Description
port	number	3001	Dashboard HTTP port
host	string	'localhost'	Bind address
open	boolean	true	Auto-open browser on start
maxTraces	number	1000	Max traces kept in memory
retentionMs	number	86400000	Trace retention (24h default)
source	'local' \| 'remote'	'local'	Local dashboard or remote collector
mode	'agent' \| 'viewer'	'agent'	Remote: send or receive traces
verbose	boolean	false	Log startup and errors