Docs/Core Concepts/Ai Agents

Understanding AI Agents

An AI agent is software that uses a language model to decide what to do next: call a tool, look something up, ask another agent, or answer. Agents run in loops and take different paths for similar inputs, which makes them harder to predict, debug and govern than a single LLM call.

In ANTS Platform, an agent is also a concrete record: a named entry in a project's agent list. Traces and observations linked to an agent roll up into agent-level cost, performance, risk and compliance views.

How agents are identified

Each agent has:

Field	Description
Agent name	A stable identifier you choose, such as `support_agent`. It is stored in lowercase and must not change.
Agent ID	16 hex characters derived from the agent name and the project ID. The SDKs compute it for you.
Display name	An optional human-readable name, such as "Support Agent (EU)". You can change it at any time without losing history.

Agents are registered automatically the first time data arrives with an agent name:

Pass agent_name (and optionally agent_display_name) on the root observation. Child observations inherit it.

python

from ants_platform import AntsPlatform ants = AntsPlatform() with ants.start_as_current_span( name="handle-ticket", agent_name="support_agent", agent_display_name="Support Agent", ): ...

The Python SDK requires an agent name on every root observation. With the LangChain callback handler, set ants_platform_agent_name in the run metadata, or the run name is used. With CrewAI, pass agent_name to the EventListener.

Changing the display name

Python: ants.update_agent_display_name("support_agent", "Support Agent (EU)")
API: PATCH /api/public/agents/{agentId}/display-name with {"displayName": "..."} (up to 255 characters)

⚠

Do not rename the agent name. A new agent name creates a new agent with a new ID and no history.

How an agent run looks in a trace

Each run of an agent is one trace. The steps it takes are observations.

text

Trace: handle-ticket agent: support_agent ├─ Span: plan │ └─ Generation: gpt-4o (tokens, cost) ├─ Span: tool:lookup_order ├─ Span: tool:issue_refund level: ERROR ├─ Generation: gpt-4o (retry after error) └─ Event: escalated_to_human

Agent pattern	What to look for
Single LLM call	One generation in the trace.
Tool-using agent (for example ReAct)	Alternating generations and tool spans. Loops show as repeated steps.
Graph agent (LangGraph)	Steps with graph metadata. The Agent Graph shows the path.
Multi-agent system	One span per sub-agent with its own generations and tools nested inside. Use one agent name per independently deployed application.

Where agents appear

View	Sidebar location	What it shows
AI Agent Center	Discover AI > AI Agent Center	Every agent with requests, cost, latency, health and risk
Traces	Discover AI > Tracing	Individual agent runs
AI Optimizer	Gauge AI > AI Optimizer	Cheaper or faster model options per agent
Risk Dashboard	Governance > Risk Dashboard	Risk and drift per agent
AI Guardrails	Governance > AI Guardrails	Guardrail settings per agent
Compliance	Governance	Agent profiles, evidence and framework coverage
Agent Tool Governance	The agent's compliance profile, or Governance in the AI Agent Center detail panel	The tools each agent may use, approval requests and behaviour alerts

The AI Agent Center and the Governance pages need the Enterprise governance entitlement. Without it, they stay in the sidebar but their content is locked.

Agent owners

Each agent can have up to 20 owners, chosen from the project's members. Owners are shown in the AI Agent Center, which can filter by owner, including Unowned. A member whose role does not otherwise include the AI Agent Center, Tracing or the Gauge AI dashboards, such as End User, sees those pages for the agents they own only. See Agent owners.

Tools an agent may use

You can approve the tools each agent may call, set rules on their arguments, require a person's approval for high-impact calls, and get alerted when an agent starts using tools or services it does not normally use. The ANTS SDKs, the Budget AI gateway and the Portkey connector enforce these permissions. Record tool calls as tool observations (for example with as_type="tool" or the SDK's tool guard) so they show as tools. See Agent Tool Governance.

Good practice

Use one stable, lowercase agent name per agent, such as support_agent.
Put the environment in the environment field, not in the agent name.
Set user and session IDs so you can follow an agent's conversations.
Record tokens on generations so agent cost is accurate.
Mark failed tool calls with level ERROR so they show in health views.