Skip to main content
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:

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.
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 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.
The response’s 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.
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