← Documentation Home

Agent Tracer Developer Guide

Overview

Package: @bluefly/agent-tracer Version: Latest License: MIT

AI Operations Intelligence - Unified observability platform for AI agents and LLM workflows with Phoenix Arize, Jaeger, Neo4j correlation, and ACE/ATLAS analytics.

Key Features

Installation

git clone https://gitlab.bluefly.io/llm/npm/agent-tracer.git
cd agent-tracer
npm install
npm run build
npm link

Quick Start

Start ACE Server

npm run dev              # Development
npm run start:ace        # Production

Start ATLAS Server

npm run atlas:dev        # Development
npm run atlas:start      # Production

Initialize Tracing

import { AgentTracer } from '@bluefly/agent-tracer';

const tracer = new AgentTracer({
  serviceName: 'my-agent',
  phoenixEndpoint: 'http://localhost:6006',
  jaegerEndpoint: 'http://localhost:14268/api/traces',
  neo4jUri: 'bolt://localhost:7687'
});

const span = tracer.startSpan('task-execution', {
  taskId: 'task-123',
  agentId: 'agent-456'
});

try {
  const result = await executeTask();
  span.setStatus({ code: SpanStatusCode.OK });
  return result;
} catch (error) {
  span.recordException(error);
  span.setStatus({ code: SpanStatusCode.ERROR });
  throw error;
} finally {
  span.end();
}

CLI Commands

Tracing

agent-tracer start
agent-tracer traces list --limit 10
agent-tracer traces get --trace-id abc123
agent-tracer traces export --output traces.json

ACE (AI Capabilities Engine)

ace start
ace score --agent-id agent-123
ace benchmark --agents agent-1,agent-2
ace capabilities --agent-id agent-123
ace report --agent-id agent-123 --output report.html

ATLAS (Analytics)

agent-tracer atlas start
agent-tracer atlas analyze --agent-id agent-123
agent-tracer atlas optimize --workflow-id workflow-456
agent-tracer atlas trends --days 30

Configuration

Environment Variables

# Service
AGENT_TRACER_PORT=3007
AGENT_TRACER_ACE_PORT=3008
AGENT_TRACER_ATLAS_PORT=3009

# Phoenix Arize
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006
PHOENIX_PROJECT=llm-agents

# Jaeger
JAEGER_COLLECTOR_ENDPOINT=http://localhost:14268/api/traces

# Neo4j (Correlation)
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password

# Qdrant (Vector Storage)
QDRANT_URL=http://localhost:6333

Examples

Phoenix Arize Integration

import { PhoenixTracer } from '@bluefly/agent-tracer/integrations/phoenix';

const phoenix = new PhoenixTracer({
  endpoint: 'http://localhost:6006',
  project: 'llm-agents'
});

const result = await phoenix.traceLLMCall({
  model: 'claude-3-5-sonnet-20241022',
  prompt: 'Explain quantum computing',
  provider: 'anthropic',
  metadata: {
    userId: 'user-123',
    sessionId: 'session-456'
  }
});

console.log('Tokens used:', result.usage.totalTokens);
console.log('Cost:', result.cost);
console.log('Latency:', result.latency);

Correlation Analysis

import { CorrelationEngine } from '@bluefly/agent-tracer/observability/correlation-engine';

const engine = new CorrelationEngine({
  neo4jUri: 'bolt://localhost:7687',
  neo4jUser: 'neo4j',
  neo4jPassword: 'password'
});

const correlations = await engine.findCorrelations({
  traceId: 'trace-abc123',
  includeMetrics: true,
  includeLogs: true
});

const rootCause = await engine.analyzeRootCause({
  incidentId: 'incident-789',
  timeWindow: '1h'
});

ACE Benchmarking

import { ACE } from '@bluefly/agent-tracer/ace';

const ace = new ACE();

const score = await ace.benchmark({
  agentId: 'agent-123',
  tasks: [
    { type: 'code-generation', count: 10 },
    { type: 'code-review', count: 5 },
    { type: 'refactoring', count: 3 }
  ]
});

console.log('Overall Score:', score.overall);
console.log('Quality:', score.quality);
console.log('Efficiency:', score.efficiency);

Observability Stack

Phoenix Arize

docker run -d -p 6006:6006 arizephoenix/phoenix:latest
open http://localhost:6006

Jaeger

docker run -d -p 16686:16686 jaegertracing/all-in-one:latest
open http://localhost:16686

Neo4j

docker run -d -p 7474:7474 -p 7687:7687 neo4j:latest
npm run migrate:neo4j:up

Testing

npm run test:unit
npm run test:integration
npm run test:e2e
npm run test:coverage

Deployment

Kubernetes

kubectl apply -f infrastructure/kubernetes/
helm upgrade --install agent-tracer ./infrastructure/helm/

Documentation