Skip to main content

Before you build a form of agent

Agents

The ten tutorials that follow each build one form of agent from a blank draft. They share a starting point, a handful of terms, one way of holding a write for approval and one publish step. This page states those once. Read it before your first tutorial and come back to it when a tutorial points here.

Who can use it: the Builder role or higher, in a tenant licensed for agents. Some prerequisites are an administrator's to provide, as the table below says.

How it works​

Every tutorial starts the same way. Switch to Studio with Switch workspace (the grid icon at the right of the top bar), open My Agents and select New agent. Pick one of the three cards, pick the Blank card on the next screen and select Continue to build. The builder then has three tabs, Setup, Test and Deploy, and a Publish button.

Terms the tutorials use​

TermWhat it means
System promptThe standing instructions the agent follows on every turn. You write it in Behavior
SlugThe short name made from the agent's name, in lower case with hyphens. It appears in the agent's address
Knowledge sourceA set of documents the platform has indexed so that an agent can search it
MCP serverA connection to another system that offers that system's actions to agents as tools
ToolOne action an agent may call, such as finding an order. A tool either reads or writes
Guardrail profileA named set of safety checks, called rails, that run on what goes into an agent, what comes out and what it passes to tools
WorkflowAn agent built as steps that run in a fixed order, started by a trigger
NodeOne box on the Visual canvas: the trigger, a step, an approval or the output
Cron expressionFive fields that say when a schedule fires: minute, hour, day of month, month and day of week. 0 6 * * 1-5 is 06:00, Monday to Friday
WebhookAn address another system sends a request to when something happens
Bearer tokenA secret the caller sends in the Authorization header to prove who is calling

Who gives you what​

You needWho provides itWhere
A team to own the agentAn Admin, a Super Admin or someone holding the User Admin grant adds you to oneTeams
A knowledge sourceYou, as a Builder, or a Knowledge AdminAdd a knowledge source
An MCP server for another systemAn AdminAdd an MCP server
A guardrail profileAn Admin, a Super Admin or someone holding the Security grantGuardrail profiles
An API keyYou, in Studio's Developer HubAuthentication
Other agents to call or route toYou or a colleague builds and publishes them firstBuild an answer agent

How a write is held for approval​

A tool is marked as one that reads or one that writes. The rule is the same for every agent that calls tools from an MCP server:

  • When you attach a tool that writes, the Tools section says how many attached tools require human approval before each call.
  • When you publish the agent, each attached tool that writes, and that has no tool-call policy yet, gets a policy that requires approval. A policy an administrator already set on the tool is left as it is.
  • From then on, a call to that tool is parked. It appears on the Control Room's Approvals page as pending, and it cannot run until an Admin or a Super Admin approves it there. One approval covers one call: once it is given, ask the agent to continue, and the call runs when the agent makes it again. See Decide tool calls.
  • An administrator can change the rule for a tool on the Policies page. A policy has two actions, Requires Approval and Block. See Policies.

A workflow holds a write differently: with an approval step that you add in Branches & approvals. The run pauses at that step until one of its reviewers decides. A workflow with a step that writes and no approval step before it cannot be published.

What a publish leads to​

Publish checks the draft first and names every blocker, each with Go to section. The screen after a publish tells you where the version landed:

  • is now live: the new version serves traffic.
  • published to a lane, promote when ready: the version runs in that environment only, and production keeps serving the previous version until you promote.
  • not live yet: the version is published but is not serving. It may be waiting on an approval; open the agent's page to see its status.

To go back, open the agent's page, select Versions and use Roll back on an earlier version. To stop an agent, use Archive in its menu on My Agents. Test, publish and versions and Manage an agent have the detail.

Limits and behaviour​

  • The Owner team list is empty. You are in no team yet. Ask an administrator to add you; the list refreshes on its own.
  • Fix N blockers stays on the publish button until every blocker is resolved. An owner team and a system prompt of at least 30 characters are both required.
  • This draft has no system prompt yet, so there is nothing to run. Add one in Behavior, then run the test again.
  • No profile selected in Guardrails. The workspace default profile applies once the agent is published, if the workspace has one. Pick a profile to give the agent its own.
  • A model does not answer in the Test tab. The AI Gateway resolves the model from the tier. Ask an administrator to check the tier's models in the Control Room.
  • A draft is private. Nothing reaches other people until you publish.

Describes the platform as of .

Was this page helpful?