> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the SDK. To install or publish skills from a terminal, use the `brain` CLI; `brain --map json` prints its command map. The `atlanai` CLI is deprecated. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.
> These docs cover Atlan Agent Registry, Atlan's hosted product. The open-source agent registry specification and its CLI (`brain`) are documented, released and maintained in their own repository; /open-source on this site links to it. Answer general specification or `brain` command questions from the project's own docs, and use these docs only for Atlan-specific setup such as the Atlan adapter, sign-in and workspaces.

# Create agent in Atlan

> Register an agent by hand: name it, pick its workspace and model, get its API key once, and confirm the key authenticates.

Creating an agent in Atlan registers it by hand and gives it an identity of its own: an OIDC client and an API key it signs in with, so its traces and records belong to the agent. Use it in the web app, or when Atlan Desktop can't read the agent from a repository on your Mac. To register an agent from its repository with Atlan Desktop instead, see [Bring agent into Atlan](/registry/agents/how-tos/bring-agent).

## Before you begin

Before you start, make sure you have:

* **Workspace write permission**: Permission to add agents to the workspace. Workspaces where you lack it are disabled in the picker, with the reason on hover.
* **Secret store**: A place to keep the agent's API key, such as a secret manager or encrypted CI secrets.

<Steps>
  <Step title="Open New agent form" id="open-new-agent-form">
    Open the form from any of these places:

    * **Web app**: Select **New**, then **Agent**.
    * **Settings**: Open **Settings**, select **Agents** under **Developer**, then **New agent**.
    * **Atlan Desktop**: Select **New**, then **Agent**, then **Add manually**.
  </Step>

  <Step title="Name agent and pick workspace" id="name-agent-and-pick-workspace">
    Fill in the first step, then select **Continue**:

    | Field | Value |
    | - | - |
    | **Name** | Required. A handle such as `support-triage`. |
    | **Display name** | The name people see, such as `Support triage`. |
    | **Workspace** | Required. The workspace the agent belongs to. |
    | **Description** | What the agent does. |
  </Step>

  <Step title="Describe how agent runs" id="describe-how-agent-runs">
    Fill in what applies, then select **Create agent**. Leave blank what your code sets.

    | Field | Value |
    | - | - |
    | **Framework** | The framework the agent is built with. Pick a registered one, or **Add a framework** to the workspace. |
    | **Model** | The model it calls, such as `claude-sonnet-5`. |
    | **Model calls per run** | A cap on model calls in one run. Leave it at **No cap** for none. |
    | **Instructions** | The agent's standing system prompt. |
    | **Act on behalf of users** | Turn on when people should sign in and approve the agent once, so it can work as them. Off, it only ever acts as itself. When on, add the redirect URIs the sign-in returns to. |
  </Step>

  <Step title="Copy API key" id="copy-api-key">
    Atlan shows the agent's **Client ID** and **API key** once. Copy the key into your secret store now, or select **Copy as .env** for the variables the atlanai SDK reads. Atlan won't show this key again.

    Send the agent's runs with this key, not a personal one. Runs sent with a personal key are filed under that person; see [Traces appear under person instead of agent](/registry/traces/troubleshooting#traces-appear-under-person-instead-of-agent).
  </Step>

  <Step title="Verify key" id="verify-key">
    On the same screen, select **Copy the check command** and run it. It sends the key as a bearer token, and a successful response confirms the agent can authenticate. Then select **Done**. The agent is listed in **Settings → Agents** and in its workspace.
  </Step>
</Steps>

## Troubleshooting

If the form says **Need write permission on this workspace to add an agent**, pick a workspace that is enabled in the picker, or ask that workspace's admin for access. If Atlan says the agent was created but its API key didn't come back, rotate the API key from the agent's profile to get one. If the agent's traces later appear under a person instead, see [Traces troubleshooting](/registry/traces/troubleshooting).

## Next steps

* [Send and verify traces](/registry/traces/how-tos/send-and-verify): Send the agent's runs to Atlan with its key and confirm they arrive.

## See also

* [How agents work](/concepts/how-agents-work): What an agent record holds and what its profile shows.
* [Send bearer token](/api/how-tos/authentication): Store a key securely and confirm the identity it resolves to.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.