Skip to main content
The Agent is DecimalAI’s unit of identity. Every trace is attributed to one agent. Every manifest version belongs to one agent. Every regression check, dataset, evaluator, and skill assignment is per-agent. If you only have one agent, this page is mostly informational. If you have many — or you’re deciding whether to split one — these are the decisions that affect everything downstream.

​
What an Agent is (and isn’t)

An agent is a name. Pick a string, pass it to decimalai.init(agent_name="support-agent") (or your framework adapter’s equivalent), and every subsequent trace is bucketed under that name. That name is the join key for six things at once — sever it, and every spoke loses its history: It is not a string you should change casually — but if you have to, the agent record can be renamed in place and keeps its history. See Renaming an agent without losing history.

​
Naming agents — what to pick

Three rules:
  1. Lowercase, hyphenated, no spaces. support-agent, not Support Agent or SupportAgent. Names appear in URLs (/agents/support-agent), CLI commands, and API payloads.
  2. Describe the role, not the implementation. support-agent is good. langchain-react-bot is bad — when you switch frameworks next year, the name lies.
  3. Use a stable prefix if you’ll have many. triage-frontline, triage-escalation, triage-billing make filtering, ACLs, and dashboards easier than three unrelated names.
Names you should avoid:
  • agent, bot, assistant (collide with default examples)
  • Anything containing your company name (you’ll never type it consistently)
  • Anything containing the model name (gets stale on every model swap)

​
When to use one agent vs. multiple

This is the most consequential decision because it affects every other concept downstream. Two questions:
If yes → one agent. They’re behaviorally the same thing, just routed differently. You can still distinguish them in trace metadata (session_id, custom tags, the route_decision span) without splitting.If no → multiple agents. Splitting now means every manifest change to one doesn’t pollute the regression report for the other.
Example: a support-agent serving customers needs strict pre-deploy regression checks; an internal-research-agent you and three engineers use can deploy looser changes.If they need different policies → split them. Evaluators and compatibility policies are per-agent.If they share the policy → keeping them as one agent is fine.
The common shape: one agent per “product surface” that gets shipped independently. A chat agent and a voice agent are two products even if they share most of the backend.

​
When NOT to split

​
Renaming an agent without losing history

Agent names are stable identifiers, but the record behind one can be renamed in place. Do it in this order:
1

Choose the new name

Pick a name that follows the naming rules. Confirm it doesn’t already exist — check the Agents list in the dashboard or GET /api/v1/agents.
2

Rename the agent record

Call POST /api/v1/agents/<old-name>/rename with {"new_name": "<new-name>"}. Because it’s the same agent record, all existing manifests, traces, and datasets stay attached — nothing is copied or merged. The old name keeps resolving via a forwarding alias, so existing URLs and agent_name= filters don’t break.
This renames in place; it is not a merge. To fold two distinct agents together, re-ingest under the surviving name instead.
3

Pass it via `decimalai.init()` in your next deploy

Update your initialization code so new traces carry the new name. The record already exists from the previous step — traces attach to it rather than creating a second agent.
4

Update references

Search your repo + workflow files for the old name. Common places: .github/workflows/decimal.yml (the regression-check action), evaluator names, dataset filters.
If you update decimalai.init() before calling the rename endpoint, the new name gets claimed by a fresh agent and the rename returns 400 — rename that new record out of the way, then re-run the rename on the original.

​
Per-agent evaluation

How strictly an agent’s traces are scored is controlled by the evaluators attached to it, not a standalone policy object. Create and manage them via the evaluators surface:
The older per-agent EvalPolicy (and the /api/v1/agents/{name}/eval-policy route) is deprecated — configure evaluators via /api/v1/evaluators instead. See Evaluations for how built-ins, @eval functions, and LLM judges combine, and Compatibility Policies for the separate per-manifest compatibility rules.

​
Sub-agents and orchestrators

If your system has an orchestrator that delegates to specialist sub-agents, register each one as its own DecimalAI agent. The orchestrator gets one manifest (tracking which sub-agents it can call); each sub-agent gets its own (tracking what each does). Cross-agent traces are linked via parent_trace_id, so the dashboard shows the full call graph. This is covered in depth in the Multi-agent guide.

​
What’s next

Tracing

Instrument your agent code so traces start landing under the agent’s name.

Manifests

How agent versions are tracked and what gets hashed into a manifest.

Multi-agent

Orchestrator / sub-agent patterns and how cross-agent traces link up.

Evaluations

Define what “good” means for each agent — built-ins, @eval functions, and LLM judges.