Before you begin
Before you start, make sure you have:- Bearer credential and shell variables: The
ATLAN_GATEWAY_URLandATLAN_TOKENvariables 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: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.1
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 records the agent’s system
prompt. The Registry stores it with the record and does not execute the
agent itself; when you run the agent in your own runtime, that runtime
decides how to use it.- Python
- JavaScript
Build the request body as a plain dict. The client is the one from
lesson 1.
name should be a stable machine identifier: lowercase, no spaces. You
use it in scripts and references, not as a display label.2
Register your agent
Send the definition to the Registry. The Registry creates the record and
returns its stable The response’s
id. This ID is how every future call (sessions,
traces, updates) refers to this agent. An agent name is unique within its
workspace, including archived agents, but not across workspaces; the ID is.
If you rerun this lesson in the same workspace, change name, or the create
returns 409.- Python
- JavaScript
identity holds two reveal-once credentials: api_key,
the agent’s machine key, valid until api_key_expires_at, and
client_secret. Neither is returned by any later read, so store them
securely before you continue. If you lose the API key, issue a new one,
which also revokes the old one, with
POST /agent/v1/agents/{agent_id}/identity/rotate and the body
{"credential_kind": "api_key"}
(client.agents.rotate_identity(agent.id, {"credential_kind": "api_key"})
in the SDK). Rotating needs manage on the agent’s workspace, which
workspace admins have.Copy the id from the output. You need it in the next step and in every
lesson that follows.3
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.Confirm the response shows the name, workspace, and instructions you
provided. If the read returns an error, see
Errors and retries before
continuing.
- Python
- JavaScript
4
Export your agent ID
Every call in the next lesson references this ID. The agent name is unique
only within its workspace, so always use the ID rather than looking the
agent up by name. Export it now so it is ready without a lookup later:
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.What’s next
Record session: Post a transcript against your agent and read it back by ID.See also
- Register agents through API: Providers, tools, tracing, and the full agent lifecycle.
- Errors and retries: Error codes, causes, and when to retry.