Submit Trace

curl -X POST http://localhost:4700/api/v1/ingest/traces \
  -H "x-api-key: a1b2c3d4e5f60718293a4b5c6d7e8f9012345678" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support-agent",
    "framework": "langchain",
    "model": "gpt-4o",
    "input": "How do I reset my password?",
    "output": "Click Forgot Password on the login page.",
    "latency_ms": 1340,
    "tool_calls": [
      { "name": "search_kb", "input": "password reset", "output": "...", "latency_ms": 210 }
    ],
    "session_id": "user_session_abc123"
  }'

from agentx import AgentX

client = AgentX.from_env()

@client.tracer.trace("customer-support-agent", framework="langchain", model="gpt-4o")
def handle(query: str) -> str:
    return chain.invoke(query)

handle("How do I reset my password?")

from agentx import AgentX

client = AgentX.from_env()

# sync=True blocks until the trace is ingested, so trace_id is available as soon as the
# `with` block exits. The decorator form above is fire-and-forget and never returns an id.
with client.tracer.trace(
    "customer-support-agent", framework="langchain", model="gpt-4o", sync=True
) as span:
    span.output = chain.invoke("How do I reset my password?")

print(span.trace_id)  # "6876abc123def456789abc01"

{
  "trace_id": "6876abc123def456789abc01",
  "reference_agent_id": "6876def456abc789012345cd",
  "queued": false
}

POST

api

ingest

traces

curl -X POST http://localhost:4700/api/v1/ingest/traces \
  -H "x-api-key: a1b2c3d4e5f60718293a4b5c6d7e8f9012345678" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support-agent",
    "framework": "langchain",
    "model": "gpt-4o",
    "input": "How do I reset my password?",
    "output": "Click Forgot Password on the login page.",
    "latency_ms": 1340,
    "tool_calls": [
      { "name": "search_kb", "input": "password reset", "output": "...", "latency_ms": 210 }
    ],
    "session_id": "user_session_abc123"
  }'

from agentx import AgentX

client = AgentX.from_env()

@client.tracer.trace("customer-support-agent", framework="langchain", model="gpt-4o")
def handle(query: str) -> str:
    return chain.invoke(query)

handle("How do I reset my password?")

from agentx import AgentX

client = AgentX.from_env()

# sync=True blocks until the trace is ingested, so trace_id is available as soon as the
# `with` block exits. The decorator form above is fire-and-forget and never returns an id.
with client.tracer.trace(
    "customer-support-agent", framework="langchain", model="gpt-4o", sync=True
) as span:
    span.output = chain.invoke("How do I reset my password?")

print(span.trace_id)  # "6876abc123def456789abc01"

{
  "trace_id": "6876abc123def456789abc01",
  "reference_agent_id": "6876def456abc789012345cd",
  "queued": false
}

Creates a PromptTrace document in your workspace and auto-creates (or updates) a reference Robot representing this external agent on the AgentX platform.

Authentication

string

required

Your workspace API key.

Body

string

required

Agent or operation label shown in the UI.

any

Agent input: string, JSON object, array, etc.

any

Agent output.

number

End-to-end wall-clock latency in milliseconds.

string

Error message if the agent run failed.

string

Framework identifier: "langchain", "crewai", "openai-agents", "anthropic", or any custom string.

string

LLM model used, e.g. "gpt-4o", "claude-sonnet-4-6".

array

Up to 50 tool calls made during the run. Excess is silently truncated.

[
  {
    "name": "search_knowledge_base",
    "input": "password reset",
    "output": "...",
    "latency_ms": 210
  }
]

string

Groups traces from the same user session or thread.

object

Arbitrary key-value metadata. Not indexed. No enforced size limit.

string

Explicit workspace ObjectId. Defaults to your API key’s workspace.

string

ISO 8601 timestamp to use as the trace’s createdAt instead of the ingest time, useful for backfilling.

object

Arbitrary performance breakdown object, stored verbatim (e.g. { total_duration_ms }).

number

Input token count. Stored as inputTokenSize when greater than 0.

number

Output token count. Stored as outputTokenSize when greater than 0.

boolean

When true, check this trace against Monitor patterns immediately, with no dashboard profile required.

array

Custom pattern ids (from POST /monitor/patterns) to restrict detection to. Only meaningful alongside monitor: true; omit to run the full default sweep (built-in checks plus every pattern enabled for the workspace) instead.

Response

string

ID of the created trace. Use this with evaluate_trace() or POST /ingest/traces/:id/evaluate.

string

ID of the reference Robot created or reused for this agent name. Appears in the AgentX UI.

boolean

Always false; traces are written synchronously.

curl -X POST http://localhost:4700/api/v1/ingest/traces \
  -H "x-api-key: a1b2c3d4e5f60718293a4b5c6d7e8f9012345678" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support-agent",
    "framework": "langchain",
    "model": "gpt-4o",
    "input": "How do I reset my password?",
    "output": "Click Forgot Password on the login page.",
    "latency_ms": 1340,
    "tool_calls": [
      { "name": "search_kb", "input": "password reset", "output": "...", "latency_ms": 210 }
    ],
    "session_id": "user_session_abc123"
  }'

from agentx import AgentX

client = AgentX.from_env()

@client.tracer.trace("customer-support-agent", framework="langchain", model="gpt-4o")
def handle(query: str) -> str:
    return chain.invoke(query)

handle("How do I reset my password?")

from agentx import AgentX

client = AgentX.from_env()

# sync=True blocks until the trace is ingested, so trace_id is available as soon as the
# `with` block exits. The decorator form above is fire-and-forget and never returns an id.
with client.tracer.trace(
    "customer-support-agent", framework="langchain", model="gpt-4o", sync=True
) as span:
    span.output = chain.invoke("How do I reset my password?")

print(span.trace_id)  # "6876abc123def456789abc01"

{
  "trace_id": "6876abc123def456789abc01",
  "reference_agent_id": "6876def456abc789012345cd",
  "queued": false
}

Get Started

Self-Hosting

Python SDK

Authentication

Body

Response

​Authentication

​Body

​Response

Authentication

Body

Response