// docs

Get started in 60 seconds

Install the SDK, drop your API key, send a trace. View it in the dashboard.

1. Install the SDK

Python 3.9 or later.

bash
pip install agentlogs-sdk

2. Get your API key

  1. 1. Sign in with email (magic link).
  2. 2. Go to Settings → Projects.
  3. 3. Create a project + an API key. Copy the key (you'll only see it once).

Then set it in your environment:

bash
export AGENTLOGS_API_KEY="al_..."
export AGENTLOGS_PROJECT="my-agent"

3. Send your first trace

python
from agentlogs import AgentLogs, StepType

client = AgentLogs(api_key="al_...")  # or set AGENTLOGS_API_KEY env var

async with await client.create_trace(name="research-agent") as trace:
    await trace.add_step(
        name="openai_call",
        step_type=StepType.LLM,
        metadata={"model": "gpt-4o", "provider": "openai"},
        tokens=1234,
        cost=0.012,
    )

Open the dashboard — your trace appears within seconds.

Decorator API (alternative)

Auto-trace an async function:

python
from agentlogs import trace_agent

@trace_agent()
async def my_agent(query: str):
    return await llm.generate(query)

Step types

python
from agentlogs import StepType

StepType.LLM        # OpenAI / Anthropic / etc. calls
StepType.TOOL       # External tool / function call
StepType.FUNCTION   # Internal function step
StepType.OTHER      # Anything else

REST API reference

All SDK calls go through these HTTP endpoints. Use directly from any language.

POST/api/v1/traces

Create a new trace. Returns trace id.

{
  "name": "agent-name",
  "input_data": { ... },     // optional
  "metadata": { ... },       // optional
  "tags": ["a", "b"]         // optional
}
POST/api/v1/traces/:id/steps

Append a step to a trace.

{
  "name": "step-name",
  "type": "llm|tool|function|other",
  "status": "success|error",
  "input": { ... },
  "output": { ... },
  "metadata": { ... },
  "tokens": 1234,
  "cost": 0.012,
  "duration_ms": 450
}
PATCH/api/v1/traces/:id

Finalize a trace.

{
  "status": "success|error",
  "output_data": { ... },
  "error_message": "...",
  "total_tokens": 5000,
  "total_cost": 0.045
}

Authorize each request with your API key:

bash
curl -X POST https://agentlogs.app/api/v1/traces \
  -H "Authorization: Bearer $AGENTLOGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent-run", "metadata": {"version": "1.0"}}'

Self-hosting

Point the SDK at your own deployment by overriding the API URL:

python
from agentlogs import configure

configure(api_url="https://logs.your-company.com")

Source code: github.com/infosiva/agenttrace