curl -X POST http://localhost:4700/api/v1/ingest/traces \
  -H "x-api-key: agtx_local_0f3c9a17d2b84e6a5c01b9f4e7d8a2c6431b5f97a0e2d4c8" \
  -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.",
    "latencyMs": 1340,
    "inputTokens": 150,
    "outputTokens": 45,
    "toolCalls": [
      { "name": "search_kb", "input": "password reset", "output": "...", "success": true }
    ],
    "sessionId": "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)  # "mJ3vQ8pTr2LqYw6bZk9Xd"

{
  "trace_id": "mJ3vQ8pTr2LqYw6bZk9Xd",
  "traceId": "mJ3vQ8pTr2LqYw6bZk9Xd",
  "deduped": false
}

{
  "error": "Invalid trace payload",
  "details": {
    "fieldErrors": { "name": ["Required"] },
    "formErrors": []
  }
}

{
  "error": "Ingest queue is full - retry with backoff (Retry-After: 1s)."
}

{
  "error": "Trace storage is unavailable - the span was not stored; retry."
}