> This page is for Voice AI Platform.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.hams.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.hams.ai/_mcp/server.

# AI agents

> Agents are built and updated in the HAMS platform; this is what you need from there to integrate with them.

AI agents are designed, tested and updated in the HAMS platform: their prompts or conversation
flow, voice, call behaviour, security settings and post-call analysis all live there, and so does
every change you make to them. The API does not create or edit agents. What your integration needs
is the **agent ID**, and the platform gives you that.

## Finding an agent's ID

Open the agent in the platform and copy its ID from the agent's page. Chat agents and voice agents
are separate agents with separate IDs; an integration that does both needs one of each.

## Where the ID is used

| Agent | What you want to do                           | Where the ID goes                                                                                                                                          |
| ----- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Chat  | Run chat sessions from your own systems       | `/ai-agents/{agent_id}/chat/…` with a secret key; see [Chat sessions and widget](/platform/chat)                                                           |
| Chat  | Chat from your web pages, or embed the widget | `/v1/ai-agents/{agent_id}/chat/…` and `/v1/ai-agents/{agent_id}/widget-config` with a public key                                                           |
| Chat  | Change how the widget looks and behaves       | `PUT /ai-agents/{agent_id}/widget-config` with a secret key                                                                                                |
| Voice | Answer inbound calls                          | Assign the agent to a number or a call flow in the platform; there is nothing to call                                                                      |
| Voice | Dial a list of numbers                        | Set the agent as the outbound agent of a telephony extension in the platform, then create [outbound batches](/platform/outbound-batches) on that extension |

Events such as completed calls and chat sessions are delivered to the webhook configured on the
agent in the platform, so a change of agent behaviour never requires a change on your side.

> **Note**
>
> Keep the agent ID in configuration, not in code. Swapping an integration to a new agent, for
> example a new version you tested in the platform, is then a configuration change.