> ## 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 atlanai CLI; `atlanai --map json` prints its command map. 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.
# Register your first Agent
> Create an agent record in the Registry, read it back by ID, and save the identifier you carry into every future session.
The Registry uses an agent record to attribute everything the agent does: every
session it runs, every trace it leaves. Without a registered agent, there is
nothing in the Registry to attribute those events to.
In this lesson, you create that record. You give the agent a name, a workspace,
and a brief description of what it does. The Registry returns a stable ID:
the identifier every future call uses to say "this is the agent that did that."
**At the end of this lesson:** your agent is registered and readable in the
Registry. You have its ID, and the Registry is ready to attribute sessions
and traces to it.
## Before you begin
Before you start, make sure you have:
* **Bearer credential and shell variables**: The `ATLAN_GATEWAY_URL` and
`ATLAN_TOKEN` variables you set in
[Connect to Registry: Prepare your shell](/api/tutorials/quickstart#prepare-your-shell)
are the same ones used here. No new credential setup is needed.
* **Workspace ID**: Any agent you register belongs to exactly one workspace.
Use the workspace list you ran in
[Connect to Registry: List your workspaces](/api/tutorials/quickstart#make-your-first-reads)
and pick the ID where you want this agent to live.
## Prepare your shell
This lesson introduces one new variable. Export your workspace ID so the
examples below can use it directly:
```bash theme={null}
export WORKSPACE_ID="" # from lesson 1
```
## Create your agent record
The registration is two calls: one write and one read back. The write creates
the record; the read back confirms it is stored exactly as you sent it.
An agent registration is valid with exactly two fields: a machine name and
a workspace. Every other field is optional, but two of them are worth
setting now.
`display_name` is what appears in the product UI: the label a person sees
when they look up the agent. `instructions` become the system prompt when
the agent runs, so a clear, specific brief here makes the agent more
predictable.
The CLI reads your agent definition from a local file. Create
`agent.yaml` in your working directory with these fields:
```yaml theme={null}
name: my-first-agent
display_name: My First Agent
instructions: "Handle requests for the Agent Registry tutorial."
model_id: claude-sonnet-5
```
`name` must be a stable machine identifier: lowercase, no spaces. You
use it in scripts and references, not as a display label. The workspace
comes from the `--workspace` flag in the next step, not the file.
Build the request body as a plain object. The `atlan` helper from
lesson 1 adds the authorization header and handles errors.
```js theme={null}
const body = {
name: "my-first-agent",
display_name: "My First Agent",
workspace_id: process.env.WORKSPACE_ID,
instructions: "Handle requests for the Agent Registry tutorial.",
model_id: "claude-sonnet-5",
};
```
If you are starting fresh without the helper, copy it from
[Connect to Agent Registry](/api/tutorials/quickstart).
Send the definition to the Registry. The Registry creates the record and
returns its stable `id`. This ID is how every future call (sessions,
traces, updates) refers to this agent. The name is not unique across
workspaces; the ID is.
```bash theme={null}
atlanai agent create --file ./agent.yaml --workspace "$WORKSPACE_ID"
```
The CLI shows the plan before writing and asks for confirmation. Review
the fields, then approve. The output includes the new agent's ID.
```js theme={null}
const agent = await atlan("/agent/v1/agents", {
method: "POST",
body: JSON.stringify(body),
});
console.log(agent.id);
```
Copy the `id` from the output. You need it in the next step and in every
lesson that follows.
A successful response means the Registry accepted the request. Reading
back by ID confirms the record is stored, readable, and matches what you
sent: a check worth making before you build on top of it.
```bash theme={null}
atlanai agent get
```
```js theme={null}
const stored = await atlan(`/agent/v1/agents/${agent.id}`);
console.log(stored);
```
Confirm the response shows the name, workspace, and instructions you
provided. If the read returns an error, see
[Errors and retries](/platform/references/errors-and-retries) before
continuing.
Every call in the next lesson references this ID. The agent name is not
guaranteed unique, so always use the ID rather than looking the agent up by
name. Export it now so it is ready without a lookup later:
```bash theme={null}
export AGENT_ID=""
```
## What you have accomplished
Your agent is a named, readable record in the Registry. It has a workspace, an
ID, and instructions that describe what it does. The Registry is ready to
attribute sessions and traces to it.
If any request returns an error, see
[Errors and retries](/platform/references/errors-and-retries): error codes,
causes, and when to retry.
## See also
[Record session](/api/how-tos/record-session): post a transcript against
your agent and read it back by ID.
[Work with Agents](/cookbooks/how-tos/agents): explore providers, tools, and
the full agent lifecycle.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.