Quickstart

# Python
pip install traceagently

# TypeScript / Node
npm install traceagently

from traceagently import TraceAgently

ta = TraceAgently(api_key="ta_live_...")

with ta.trace(agent_id="support-bot", task="Refund user #123") as trace:
    trace.thought("I need to check the order database")
    trace.tool_call("check_order", {"user_id": 123})
    trace.tool_result({"status": "delivered"})
    trace.final_response("Cannot refund a delivered order")

from traceagently import TraceAgently

ta = TraceAgently(
    api_key="ta_live_...",         # required
    base_url="https://api.traceagently.com",  # optional override
    timeout=10,                   # seconds, default 10
)

with ta.trace(
    agent_id="billing-agent",
    task="Process invoice INV-9912",
    # any extra kwargs become trace metadata
    model="gpt-4o",
    framework="langgraph",
    temperature=0.2,
) as trace:
    # your agent logic here
    pass
# trace is automatically marked "completed" on exit
# raises → trace marked "failed" and exception re-raised

trace.thought("The user wants a refund. I should check delivery status first.")

trace.tool_call("check_order", {"order_id": "ORD-4521", "user_id": 123})

trace.tool_result({"status": "delivered", "delivered_at": "2025-03-20T14:22:00Z"})

try:
    result = call_external_api()
except Exception as e:
    trace.error(str(e))
    # handle gracefully or re-raise

trace.final_response("Cannot refund a delivered order. Contact support if this is an error.")

import openai
from traceagently import TraceAgently

ta = TraceAgently(api_key="ta_live_...")
client = openai.OpenAI()

def run_agent(user_request: str):
    with ta.trace(agent_id="gpt4o-agent", task=user_request, model="gpt-4o") as trace:
        trace.thought("Deciding which tool to use")

        response = client.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": user_request}]
        )
        answer = response.choices[0].message.content

        trace.final_response(answer)
    return answer

import { TraceAgently } from 'traceagently'

const ta = new TraceAgently({
  apiKey: 'ta_live_...',          // required
  baseUrl: 'https://api.traceagently.com',  // optional
  timeout: 10_000,                // ms, default 10 000
})

const trace = await ta.startTrace({
  agentId: 'support-bot',
  task: 'Refund user #123',
  // any extra fields become trace metadata
  model: 'gpt-4o',
  framework: 'langchain',
})

await trace.thought('Checking order status before deciding on refund')

await trace.toolCall('check_order', { userId: 123, orderId: 'ORD-4521' })

await trace.toolResult({ status: 'delivered', deliveredAt: '2025-03-20T14:22:00Z' })

await trace.error('External API returned 503 — retrying')

await trace.end('Cannot refund a delivered order')
// or without a final response:
await trace.end()

import OpenAI from 'openai'
import { TraceAgently } from 'traceagently'

const ta = new TraceAgently({ apiKey: 'ta_live_...' })
const openai = new OpenAI()

async function runAgent(userRequest: string) {
  const trace = await ta.startTrace({
    agentId: 'gpt4o-agent',
    task: userRequest,
    model: 'gpt-4o',
  })

  try {
    await trace.thought('Processing request')

    const res = await openai.chat.completions.create({
      model: 'gpt-4o',
      messages: [{ role: 'user', content: userRequest }],
    })
    const answer = res.choices[0].message.content ?? ''

    await trace.end(answer)
    return answer
  } catch (err) {
    await trace.error(String(err))
    await trace.end()
    throw err
  }
}

Authorization: Bearer ta_live_<your-key>

{
  "agentId":  "support-bot",
  "task":     "Refund user #123",
  "metadata": {
    "model":       "gpt-4o",
    "framework":  "langgraph",
    "temperature": 0.2
  }
}

{
  "traceId":   "trc_01j9z4k8...",
  "status":    "running",
  "startedAt": 1711718400000
}

{
  "type":      "tool_call",
  "content":   "check_order",
  "tokens":    128,
  "metadata":  { "inputs": { "user_id": 123 } },
  "timestamp": 1711718401234
}

{
  "eventId": "evt_0a3x7p...",
  "traceId": "trc_01j9z4k8..."
}

{
  "traces": [
    {
      "traceId":          "trc_01j9z4k8...",
      "agentId":          "support-bot",
      "task":             "Refund user #123",
      "status":           "completed",
      "startedAt":        1711718400000,
      "endedAt":          1711718409123,
      "totalTokens":      842,
      "estimatedCostUsd": 0.0024
    }
  ],
  "nextCursor": "cur_abc..."
}

{
  "traceId":  "trc_01j9z4k8...",
  "agentId":  "support-bot",
  "task":     "Refund user #123",
  "status":   "completed",
  "events": [
    { "eventId": "evt_001", "type": "thought",       "content": "Check order DB",         "timestamp": 1711718400100 },
    { "eventId": "evt_002", "type": "tool_call",    "content": "check_order",            "timestamp": 1711718401200 },
    { "eventId": "evt_003", "type": "tool_result",  "content": "{\"status\":\"delivered\"}",  "timestamp": 1711718403400 },
    { "eventId": "evt_004", "type": "final_response", "content": "Cannot refund...",       "timestamp": 1711718408900 }
  ]
}

{
  "error":   "Monthly limit reached. Upgrade at traceagently.com/pricing",
  "code":    "limit_reached",
  "status":  429
}

thought → tool_call → tool_result → thought → tool_call → ... → final_response