Agent Attribution & Tracing

PraisonAI provides built-in attribution and tracing support for multi-agent systems. This enables tracking which agent made which request, debugging complex workflows, and monitoring agent behavior.

Quick Start

Simple Usage

import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'You are a helpful assistant',
  llm: 'openai/gpt-4o-mini',
  name: 'helper-agent'  // Agent ID for attribution
});

// Attribution headers are automatically injected
const response = await agent.chat('Hello');

// Access attribution info
console.log('Agent:', agent.name);
console.log('Session:', agent.getSessionId());
console.log('Run:', agent.getRunId());

Attribution Headers

When using AI SDK backend, PraisonAI automatically injects attribution headers:

Header	Description
`X-Agent-Id`	Unique identifier for the agent
`X-Run-Id`	Unique identifier for the current run
`X-Session-Id`	Session identifier for conversation continuity
`X-Trace-Id`	Trace identifier for distributed tracing
`X-Parent-Span-Id`	Parent span for nested operations

Backend Resolution with Attribution

import { resolveBackend } from 'praisonai';

const { provider, source } = await resolveBackend('openai/gpt-4o-mini', {
  attribution: {
    agentId: 'my-agent',
    runId: 'run-123',
    sessionId: 'session-456',
    traceId: 'trace-789'
  }
});

// All requests through this provider include attribution headers
const result = await provider.generateText({
  messages: [{ role: 'user', content: 'Hello' }]
});

Multi-Agent Attribution

Each agent in a multi-agent system gets unique attribution:

import { Agent, AgentTeam } from 'praisonai';

const researcher = new Agent({
  name: 'researcher',
  instructions: 'Research the topic'
});

const writer = new Agent({
  name: 'writer',
  instructions: 'Write based on research'
});

const agents = new AgentTeam([researcher, writer]);

// Each agent's requests have different X-Agent-Id headers
await agents.start();

// Verify attribution
console.log('Researcher ID:', researcher.name);
console.log('Writer ID:', writer.name);
console.log('Researcher Session:', researcher.getSessionId());
console.log('Writer Session:', writer.getSessionId());

Parallel Agent Isolation

Attribution ensures parallel agents don’t interfere:

import { Agent, AgentTeam } from 'praisonai';

const agent1 = new Agent({ name: 'agent-1', instructions: 'Task 1' });
const agent2 = new Agent({ name: 'agent-2', instructions: 'Task 2' });
const agent3 = new Agent({ name: 'agent-3', instructions: 'Task 3' });

const agents = new AgentTeam({
  agents: [agent1, agent2, agent3],
  process: 'parallel'
});

// All three agents run in parallel with isolated attribution
const results = await agents.start();

// Each has unique run IDs
console.log('Agent 1 Run:', agent1.getRunId());
console.log('Agent 2 Run:', agent2.getRunId());
console.log('Agent 3 Run:', agent3.getRunId());

Custom Attribution Context

Provide custom attribution for advanced use cases:

import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'You are helpful',
  llm: 'openai/gpt-4o-mini',
  name: 'custom-agent',
  sessionId: 'my-custom-session',
  runId: 'my-custom-run'
});

// Custom IDs are used in attribution headers
const response = await agent.chat('Hello');

Tracing Integration

OpenTelemetry Integration

import { Agent } from 'praisonai';
import { trace } from '@opentelemetry/api';

const tracer = trace.getTracer('my-app');

await tracer.startActiveSpan('agent-operation', async (span) => {
  const agent = new Agent({
    instructions: 'You are helpful',
    llm: 'openai/gpt-4o-mini',
    telemetry: true  // Enable telemetry
  });
  
  try {
    const response = await agent.chat('Hello');
    span.setStatus({ code: 0 });
  } catch (error) {
    span.setStatus({ code: 2, message: error.message });
    throw error;
  } finally {
    span.end();
  }
});

Custom Telemetry

import { resolveBackend } from 'praisonai';

const { provider } = await resolveBackend('openai/gpt-4o-mini', {
  telemetry: {
    isEnabled: true,
    functionId: 'my-function',
    metadata: {
      environment: 'production',
      version: '1.0.0'
    }
  }
});

Debugging with Attribution

Use attribution to debug multi-agent issues:

import { Agent, AgentTeam } from 'praisonai';

const agents = new AgentTeam([
  new Agent({ name: 'analyzer', instructions: 'Analyze data' }),
  new Agent({ name: 'processor', instructions: 'Process results' }),
  new Agent({ name: 'reporter', instructions: 'Generate report' })
]);

// Enable verbose logging to see attribution
process.env.PRAISON_VERBOSE = 'true';

await agents.start();

// Logs will show which agent made each request:
// [analyzer] Sending request with X-Agent-Id: analyzer, X-Run-Id: ...
// [processor] Sending request with X-Agent-Id: processor, X-Run-Id: ...
// [reporter] Sending request with X-Agent-Id: reporter, X-Run-Id: ...

Attribution in Workflows

import { AgentFlow, Agent } from 'praisonai';

const extractor = new Agent({ name: 'extractor', instructions: 'Extract data' });
const transformer = new Agent({ name: 'transformer', instructions: 'Transform data' });
const loader = new Agent({ name: 'loader', instructions: 'Load data' });

const flow = new AgentFlow('data-pipeline')
  .agent(extractor, 'Extract data from source')
  .agent(transformer, 'Transform the extracted data')
  .agent(loader, 'Load data to destination');

// Each step has isolated attribution
const { output } = await flow.run(inputData);

Accessing Attribution Data

const agent = new Agent({
  name: 'my-agent',
  instructions: 'You are helpful'
});

// Get attribution identifiers
const agentId = agent.name;
const sessionId = agent.getSessionId();
const runId = agent.getRunId();

// Get backend source
const backendSource = agent.getBackendSource();

console.log({
  agentId,
  sessionId,
  runId,
  backendSource
});

Best Practices

Use meaningful agent names

: Names appear in attribution headers

Preserve session IDs

: Reuse session IDs for conversation continuity

Log run IDs

: Store run IDs for debugging and auditing

Enable telemetry in production

: Track performance and errors

Use trace IDs

: Connect related operations across services

TypeScript Types

import type { AttributionContext } from 'praisonai';

const attribution: AttributionContext = {
  agentId: 'my-agent',
  runId: 'run-123',
  sessionId: 'session-456',
  traceId: 'trace-789',
  parentSpanId: 'span-abc'
};

Attribution CLI

CLI commands

Telemetry

Usage telemetry

​Agent Attribution & Tracing

​Quick Start

​Attribution Headers

​Backend Resolution with Attribution

​Multi-Agent Attribution

​Parallel Agent Isolation

​Custom Attribution Context

​Tracing Integration

​OpenTelemetry Integration

​Custom Telemetry

​Debugging with Attribution

​Attribution in Workflows

​Accessing Attribution Data

​Best Practices

​TypeScript Types

​Related