Skip to main content

​
What tracing gives you

Tracing captures each agent run and tool call so you can:
  • See end-to-end execution paths for multi-step agents
  • Inspect tool inputs and outputs
  • Debug failures with rich span data
  • Monitor usage across environments
Celesto tracing view with agent run timeline and tool spans

​
Quick setup

1

Set your Celesto API key

Add your Celesto API key to the environment.
export CELESTO_API_KEY="cel_..."
2

Enable tracing

Choose the setup that fits your workflow.
3

Verify

Run your agent once, then open the Celesto dashboard and confirm the trace appears.
You should see a trace entry with spans for the model call and any tools.

​
Environment variables

​
CELESTO_API_KEY
string
required
Enables tracing and authenticates trace uploads to Celesto.
​
CELESTO_DISABLE_AUTO_TRACING
boolean
default:"false"
Disable automatic tracing when CELESTO_API_KEY is set.
​
CELESTO_BASE_URL
string
default:"https://api.celesto.ai/v1"
Custom Celesto API base URL for self-hosted or private deployments.

​
Advanced usage

Use these patterns only when you need more control than the quick setup.

​
Customize batching and exporter settings

import os

from agentor import Agentor
from agentor.tracer import setup_celesto_tracing

os.environ["CELESTO_DISABLE_AUTO_TRACING"] = "true"

processor = setup_celesto_tracing(
    endpoint="https://api.celesto.ai/v1/traces/ingest",
    token=os.environ["CELESTO_API_KEY"],
    replace_default=True,
    batch_delay=2.0,
    max_batch_size=512,
)

agent = Agentor(
    name="Support Agent",
    model="gpt-5-mini",
)
result = agent.run("Summarize the latest support tickets.")

processor.force_flush()
processor.shutdown()
setup_celesto_tracing should run once at startup before you execute any agents.

​
Attach per-run metadata for grouping

Each agent.run(...) call creates a trace automatically. Use the underlying runner if you need a group_id or metadata per run. 
from agentor import Agentor
from agentor.core.agent import Runner
from agentor.tracer import get_run_config, setup_celesto_tracing

setup_celesto_tracing(
    endpoint="https://api.celesto.ai/v1/traces/ingest",
    token="cel_...",
)

agent = Agentor(
    name="Support Agent",
    instructions="You help triage tickets.",
    model="gpt-5-mini",
)
run_config = get_run_config(
    group_id="ticket-queue-jan-13",
    metadata={"team": "support", "priority": "p1"},
)

result = Runner.run_sync(
    agent.agent,
    "Summarize today's urgent tickets.",
    run_config=run_config,
)

​
Security considerations

Traces can include model inputs and tool outputs. Avoid sending secrets or sensitive data unless you intend to store it in Celesto.

​
Troubleshooting

  • Confirm you set CELESTO_API_KEY in the same environment where you run the agent.
  • If you set CELESTO_DISABLE_AUTO_TRACING=true, enable tracing explicitly or call setup_celesto_tracing.
  • If you use a custom endpoint, verify CELESTO_BASE_URL points to your Celesto API URL.