Register your first Agent

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 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 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:

export WORKSPACE_ID="<your-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.

Choose your agent fields

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.

CLI
JavaScript

The CLI reads your agent definition from a local file. Create agent.yaml in your working directory with these fields:

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.

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.

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.

CLI
JavaScript

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.

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.

Read your agent back

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.

CLI
JavaScript

atlanai agent get <agent-id>

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 before continuing.

Export your agent ID

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:

export AGENT_ID="<your-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: error codes, causes, and when to retry.

Get started

Work with agents

Reference

Before you begin

Prepare your shell

Create your agent record

What you have accomplished

See also

​Before you begin

​Prepare your shell

​Create your agent record

​What you have accomplished

​See also

Before you begin

Prepare your shell

Create your agent record

What you have accomplished

See also