Agent identity
BothHow agent and environment names appear when sending traces to the Traccia platform.
When you send traces to the Traccia platform, each trace is labeled with an agent and an environment. You can leave these unset and still see traces—or set them for clearer filtering and dashboards.
Defaults
If you do not set agent_id or agent_name, the SDK uses your service name for both. So your traces still show a sensible label (e.g. your app or script name) without any extra configuration.
If you do not set env, the platform shows unknown-environment for that trace.
Multi-agent orchestrators
In a multi-agent system you often have a host service (portal, API, backend) that runs many logical agents. You usually do not want this host service to show up as an agent in the Traccia UI – only the individual agents it orchestrates.
To support this pattern, the SDK exposes a service_role flag. When you set service_role="orchestrator", the ingestion service never registers the host service as an agent and never falls back to service.name as agent.id. All traces and metrics are attributed to the logical agents you tag via agent_id / runtime_config.run_identity().
from traccia import init
# Multi-agent host service (e.g. demo portal, orchestrator API)init( api_key="tr_live_xxxxxxxxxxxx", service_name="traccia-demo-portal", service_role="orchestrator", # mark as multi-agent host, not a logical agent)With this flag set, the Traccia platform only shows the logical agents.
Using the Traccia platform?
Quickstart (no identity set)
This is enough to get started. Traces will appear under your service name.
from traccia import init
init()Recommended for the platform
Set agent and environment in init():
from traccia import init
init( agent_id="research-agent", agent_name="Research Agent", env="production")Or use environment variables: TRACCIA_AGENT_ID, TRACCIA_AGENT_NAME, TRACCIA_ENV.
Next steps
© 2026 Traccia.