Design an agent

This guide creates an agent step by step. For the concept behind it, read Agents first.

Goal

Create a working agent with a charter, a tool set, and an autonomy mode, then land on its workspace ready to test.

Prerequisites

• The platform.agents.write capability. It gates the builder; without it the New agent page returns a permission error.
• To let the agent’s service account WRITE later, you also need platform.iam.write. This guide creates a read-and-propose agent, which does not require it.

Steps

To open the builder, go to Admin → AI → Agents and click New agent. That opens the guided builder, a single form with four sections and an activation checklist.

1. Set the identity and charter

Type an Agent name. The Slug derives from it automatically (lowercase letters, numbers, hyphen, underscore) and becomes the agent’s stable identifier. A starter Charter appears too. The charter is the system prompt that drives every turn, so edit it to describe the job, the boundaries, and the output contract.

You should see the slug fill in as you type the name, and the charter update to name your agent.

2. Choose the runtime contract

In Runtime Contract, pick a Model (or keep the tenant default), leave Status on Draft for now, and choose an Autonomy mode:

• Propose. The agent drafts its writes as approval requests; a human applies them.
• Bounded. The agent may execute its granted write tools directly, with no destructive operations.
• Autonomous. The agent may execute any granted tool directly.

Propose mode also shows a default-approver picker. You should see it appear when Propose is selected.

3. Grant tools

In Tool Grants, select the tools the agent may call. Read tools like crud_read and query_records let it gather context; propose_changes routes its writes to approval. Most agents need at least one read tool before they can decide anything.

You should see each tool you check appear in the Runtime Preview on the right.

An agent acts as its own service account, not as you. A read tool runs immediately, but a write tool executes only when the agent is in bounded or autonomous mode AND its service account holds a write-granting role. Start in propose mode so every write stays behind human review, and add service-account roles later from the agent’s workspace (that assignment needs platform.iam.write).

4. Check activation and create

The right rail shows the Activation Checklist: valid identity, a charter, at least one context tool, propose_changes for propose mode, and configured approval routing. Status can switch to Active only when every item passes; otherwise create the agent as a draft and finish it later.

Click Create draft agent (the button reads Create active agent once the checklist is green). You land on the agent’s workspace, where a readiness rail shows what is left to configure and a test run is one click away.

Verification

You know it worked when:

• The new agent appears in the fleet list with status Draft.
• Its workspace opens with the readiness rail scored and the anatomy canvas rendered.
• The charter, granted tools, and autonomy mode you chose show on the workspace.

Troubleshooting

Symptom	Cause	Fix
Active status is disabled	The activation checklist has an unmet item, often missing approval routing in propose mode	Add a default approver, or create the agent as a draft and resolve the checklist on the workspace
The slug field shows an error	The slug has characters other than lowercase letters, numbers, hyphen, or underscore	Edit the slug to match the allowed characters
A granted write tool never executes at run time	The agent is in propose mode, or its service account lacks a write role	Set bounded or autonomous mode and grant the service account a write role (needs platform.iam.write)

Related

• Agents: what an agent is and how the spec is validated.
• Plans and governance: how proposed writes reach approval.
• Safety model: least privilege, propose mode, and human-in-the-loop.