Agents
Create an agent, decide what it may reach and do, test it in the Agent Studio, run it by hand, on a schedule or from a webhook, and stop it at once when you need to.
An agent is a digital teammate that works within the limits you set. It has instructions, a model, the knowledge it may read, the tools it may call, a schedule and limits. Everything is closed unless you allow it.
Open AI > Agents. The top shows Work handled today, Waiting for your yes (tool calls that need a person), Failed today and Spend today, then every agent you may see with its runs, cost and open alerts.
Create an agent
AI > Agents > New agent.
Give it a name and say what it is for.
Choose models: the model it uses (from your plan's model names).
Secrets: each secret it needs as a Variable name (such as
API_TOKEN), picked from the Vault or added now.What it may reach: the outside hosts and ports it may call. Nothing else is reachable.
Create. It is a draft until you deploy it from its page. Values shown at this point (the model key and the webhook token) are shown only now: copy what you need.
Creating agents needs a role with that right in the organisation or a team; an organisation admin can give it to you.
Configure it
On the agent's page, the Configure tab has four cards:
Card | What you set |
|---|---|
General | Name, the name in code, description |
Instructions and model | What it is told before every run, and its model. Save as new version with a note of What changed |
Knowledge and permissions | Knowledge collections it reads, skills, and which of your rights it may use |
Schedule and limits | A cron schedule in UTC ( |
Guardrails add rules on top: Allowed tools and Denied tools as patterns (files_*, *_delete), tools that need a person's yes (jobs_run), input and output rules (for example block card numbers), and Pause on a warning signal. An organisation admin sets guardrail defaults every agent starts under; an agent's own guardrails can only add to them, never loosen them.
What an agent may do
An agent's effective rights are the agent's own permissions AND the person it works for AND its holder (who deployed it); a refusal from any of them wins. A read-only person using a powerful agent can only read. With no person (a scheduled run) it gets the agent's and the holder's rights only. If the holder leaves the organisation, the agent pauses.
Test it in the Agent Studio
The agent's page has the tabs Overview, Runs, Configure, Versions, Alerts, Logs and Test, and the buttons Deploy, Run, Studio and Pause. Click Studio to improve it.
Test chat: every message is a test run of the draft. Each answer shows its steps, cost and time; mark Good answer or Bad answer with a note.
Save as test case: a question with checks (the answer contains a word, a tool was called). Run test cases and Compare two versions: a case that passes on the first and fails on the second got worse.
The optimizer reads your notes and proposes changes; Try on test cases, then apply them to the draft only.
Versions: each saved version is fixed. Activate one to make it live, Deactivate to stop using it; compare any two field by field.
Run it
Start run on the agent's page (optionally with What to do; empty runs its instructions as they are). A holder can also choose Run with no person.
On its schedule.
From another program:
POST /api/agents/{id}/runs, or a webhook with its token (see the developer docs).
Watch a run live: In plain words (what it did, step by step), Steps (each model and tool call), What filled its context, Tools and servers (what it called and what was refused), Agent calls and Events.
Approvals, stopping and safety
A tool call that needs a person waits under Waiting for your yes and in Review. Only that run waits; the request expires after 24 hours. Approve or Refuse.
Stop this run ends one run. Pause stops the agent and Resume starts it again; More actions > Stop for good… stops every run at once and revokes its tokens.
A watchdog checks progress, not just that it is alive: a run that makes no progress for 5 minutes is restarted from its last checkpoint; after 3 failures the agent pauses and an alert goes up.
Its runner output keeps the last 500 lines from its sandbox, with secrets taken out. The Audit trail records every change with who and why.
To build agents in code, see the agent kit (ADK).