AgentTraceHQ
FeaturesHow It WorksPricingDocsAboutLog InGet Started

Documentation

Everything you need to instrument, monitor, and audit your AI agents.

On this page

    Quick Start

    Authentication

    Trace Schema

    SDK Reference

    Frameworks

Quick Start

Get up and running with AgentTraceHQ in under 5 minutes. Install the SDK, initialize it with your API key, and send your first trace.

1. Install the SDK
Terminal
npm install @agenttracehq/sdk
2. Initialize
index.js
import { AgentTraceHQ } from '@agenttracehq/sdk';

const ath = new AgentTraceHQ({
  apiKey: process.env.AGENTTRACEHQ_API_KEY,
  agentId: 'my-agent-001',
});
3. Send your first trace
index.js
// Send your first trace
await ath.trace({
  event: 'llm.completion',
  input: { prompt: 'Summarize this document...' },
  output: { text: 'The document discusses...' },
  metadata: {
    model: 'gpt-4',
    tokens: 342,
    latencyMs: 1250,
  },
});

console.log('Trace sent!');
Authentication

All API requests require an API key. You can generate keys from your Dashboard > Settings > API Keys page. Keys are prefixed with ath_live_ for production and ath_test_ for development.

Pass your API key via the SDK constructor or as a Bearer token in the Authorization header for direct API calls.

Direct API usage
// API keys are passed in the Authorization header
const response = await fetch('https://api.agenttracehq.com/v1/traces', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ath_live_abc123...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event: 'tool.call',
    input: { tool: 'web_search', query: 'latest AI news' },
    output: { results: [...] },
  }),
});
Trace Schema

Every trace is an immutable record of an agent action. Traces are cryptographically linked via hash chains, ensuring tamper-proof audit trails. Below is the full trace object schema:

Trace Object
{
  "id": "trc_a3f29c1e...",
  "agentId": "agent-001",
  "sessionId": "ses_7c1eb9d4...",
  "event": "llm.completion",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "input": {
    "prompt": "Analyze the sales data...",
    "context": { ... }
  },
  "output": {
    "text": "Based on the data...",
    "confidence": 0.95
  },
  "metadata": {
    "model": "gpt-4",
    "tokens": 512,
    "latencyMs": 1800,
    "cost": 0.032
  },
  "parentTraceId": "trc_parent...",
  "hash": "sha256:e5a8f2c1...",
  "previousHash": "sha256:b9d47c1e...",
  "tags": ["production", "sales-analysis"]
}
SDK Reference
trace(event)

Log a single trace event. This is the primary method for recording agent actions. Each trace is automatically assigned a unique ID, timestamp, and hash-chain link.

trace()
// ath.trace(event) - Log a single trace event
await ath.trace({
  event: 'tool.call',          // Event type (required)
  input: { ... },              // Input data (optional)
  output: { ... },             // Output data (optional)
  metadata: { ... },           // Arbitrary metadata (optional)
  tags: ['prod', 'v2'],        // Searchable tags (optional)
  parentTraceId: 'trc_...',    // Parent trace for nesting (optional)
});
session(options)

Start a session to logically group related traces. Useful for multi-step agent workflows where you want to track an entire conversation or task from start to finish.

session()
// ath.session(options) - Start a session to group traces
const session = ath.session({
  name: 'customer-support-flow',
  metadata: { userId: 'usr_123' },
});

// All traces within the session are automatically linked
await session.trace({ event: 'llm.completion', ... });
await session.trace({ event: 'tool.call', ... });

// End the session
await session.end();
flush()

Ensure all pending traces in the buffer are sent to the AgentTraceHQ API. Critical for serverless environments where the process may terminate before the buffer is flushed.

flush()
// ath.flush() - Ensure all pending traces are sent
// Call this before your process exits
await ath.flush();

// Useful in serverless environments
export async function handler(event) {
  const result = await processWithAgent(event);
  await ath.flush(); // Ensure traces are sent before Lambda exits
  return result;
}
Frameworks

AgentTraceHQ integrates with popular AI agent frameworks out of the box. Use our callback handlers to automatically capture all agent activity with zero manual instrumentation.

LangChain
LangChain Integration
import { AgentTraceHQ } from '@agenttracehq/sdk';
import { ChatOpenAI } from '@langchain/openai';
import { AgentExecutor } from 'langchain/agents';

const ath = new AgentTraceHQ({
  apiKey: process.env.AGENTTRACEHQ_API_KEY,
  agentId: 'langchain-agent',
});

// Wrap your LangChain agent with tracing
const agent = AgentExecutor.fromAgentAndTools({
  agent: myAgent,
  tools: myTools,
  callbacks: [ath.langchainCallback()],
});

// All LLM calls, tool invocations, and chain steps
// are automatically traced
const result = await agent.invoke({
  input: 'What is the weather in San Francisco?',
});
CrewAI
CrewAI Integration
from agenttracehq import AgentTraceHQ

ath = AgentTraceHQ(
    api_key="ath_live_abc123...",
    agent_id="crewai-team"
)

from crewai import Agent, Task, Crew

# Instrument CrewAI with the callback
researcher = Agent(
    role="Researcher",
    goal="Find latest AI papers",
    callbacks=[ath.crewai_callback()],
)

writer = Agent(
    role="Writer",
    goal="Summarize findings",
    callbacks=[ath.crewai_callback()],
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
)

# Every agent step, delegation, and tool call is traced
result = crew.kickoff()