Skip to main content
GET
Retrieve an Agent by ID
Fetch the complete configuration for a single agent by ID. Useful for auditing, debugging, cloning, or building admin UIs on top of TruGen.

When to use

  • Debugging: confirm the live configuration matches what you think it is
  • Cloning: read a working agent, tweak, and re-create as a new agent
  • Admin dashboards: build an internal view of your organization’s agents
  • Backup: snapshot configuration before making changes

What’s returned

The full agent object as it exists on the server, including:
  • Top-level fields (agent_name, agent_system_prompt, is_active, record, callback_url, etc.)
  • All configured avatars with STT, LLM, TTS, and turn-detection settings
  • Attached knowledge bases (by ID)
  • Attached tools and MCPs (by ID)
  • Attached guardrails (full objects: key, category, prompt, response_message, callback_url)
  • Widget configuration

Common gotchas

  • The response can be large. Agents with many avatars, tools, and knowledge bases produce sizable responses. Cache aggressively on your side.
  • Attachments are returned as IDs. Attached tools, knowledge bases, and MCPs are returned as IDs: fetch the individual resources separately if you need their full configuration.
  • Not found returns 404. If the agent was deleted, the endpoint returns 404.

Next steps

Authorizations

x-api-key
string
header
required

Path Parameters

id
string<uuid>
required

Unique identifier for the Agent

Response

Agent retrieved successfully

id
string<uuid>

Unique identifier for the agent.

Example:

"b63c2a53-266b-4b43-a71b-7ea8b5e2e916"

agent_name
string

Display name of the agent.

Example:

"Customer Support Agent"

agent_system_prompt
string

Foundational system instruction used by this agent.

Example:

"You are a helpful AI assistant that handles customer service inquiries."

avatars
object[]

List of avatars associated with this agent.

callback_events
string[]

Webhook events that should trigger callbacks.

Example:
callback_url
string

Webhook endpoint URL to send callback events to.

Example:

"https://webhooks.example.com/agent-events"

config
object

Agent-level configuration properties.

knowledge_base
object[] | null

List of knowledge bases attached to this agent.

tool
object[] | null

List of tools attached to this agent.

guardrail
object[] | null

Guardrails attached to this agent, returned in full (not by ID only).

mcp
object[] | null

List of MCP attached to this agent.

record
boolean

Determines whether voice call recordings should be stored.

Example:

true

created_at
string<date-time>

Timestamp indicating when the agent was created.

Example:

"2025-12-01T10:20:30.000Z"

updated_at
string<date-time>

Last updated timestamp for the agent.

Example:

"2025-12-03T14:50:00.000Z"