Parallel Runs in One Process

SDK

Run multiple agents safely from a single process using run_identity() and force_flush().

When you run many agents from a single long-lived process (for example an API server or orchestrator), you should initialize tracing once per process and use run_identity() to set agent identity per request or run.

Avoid per-request init/stop

Calling init() and stop_tracing() on every request tears down the global tracer provider and can cause lost or truncated traces when requests overlap. Instead, init once per process and use run_identity().

Recommended pattern

  1. Call init() once at process startup.
  2. For each logical agent run, provide the identity dynamically. In Python, use runtime_config.run_identity(...). In the TypeScript SDK, set the agent.id and env attributes directly on the root span.
  3. Use force_flush() (Python) or Traccia.getTracerProvider().forceFlush() (Node) after a run to flush spans/metrics without shutting down the tracer provider.
parallel_runs.py
python
from traccia import init, span, force_flush, runtime_config


# 1) Init once per process
init(service_name="multi-agent-service", auto_start_trace=False)


def run_agent(agent_id: str, env: str, input: dict):
    # 2) Set identity for this run only
    with runtime_config.run_identity(agent_id=agent_id, agent_name=agent_id, env=env):
        with span("agent.run") as root:
            root.set_attribute("agent.id", agent_id)
            root.set_attribute("agent.run.mode", "api")
            # ... call your agent/orchestrator code here ...


    # 3) Flush without stopping tracing
    force_flush(5.0)

When to use this

  • API servers that expose many agents from one process.
  • Worker / orchestrator processes that dispatch multiple agents in parallel.
  • Demo environments where several agents share one backend.

Identity resolution in the platform

The platform resolves agent identity from span attributes first (for example agent.id), then from resource attributes (including service.name). Using run_identity() and setting agent.id on your root spans ensures each trace is attributed to the correct agent even when many agents share a process.

For a deeper dive into how identity works, see Agent Identity and the Multi-Agent guide.

© 2026 Traccia.