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. Renaming an agent is fine; you just lose continuity if you do it.

​
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 webhook 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

ScenarioSplit?Do instead
Different prompts for different usersNoSame agent — vary the prompt via the rendered_input.
A/B testing two variantsNoSame agent — log both via manifest_id (the active variant is the baseline; run a regression check on the experimental variant).
Multiple tools sometimes called sequentiallyNoSame agent — tools are part of the manifest, not separate agents.

​
Renaming an agent without losing history

Agent names are stable identifiers — they aren’t first-class entities you rename in place. To rebrand:
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

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

Update your initialization code. The next trace ingested under the new name creates the agent fresh.
# before
decimalai.init(agent_name="support-bot")

# after
decimalai.init(agent_name="support-agent")
3

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.
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 forget step 3, the old agent stays in the sidebar with its frozen history — annoying but not destructive.

​
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: 
# List evaluators (optionally scoped to one agent)
decimalai evaluators list --agent support-agent

# See available templates, then attach one to a single agent
decimalai evaluators templates
decimalai evaluators add --template helpfulness_judge --agent support-agent
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.