Agent Builder

The Agent Builder is an agent that builds agents. Describe what you need in the chat; it learns the process from you, reads what the application defines, drafts the agent with its skill, procedures and any tools, saves them once you approve, and tries the agent before handing it over.

It is for AI administrators only. It follows the practices that make an agent reliable — one task, named tools, form changes through procedures — so what it builds is a good starting point to review, not a finished product.

Build an agent

  1. Open the AI chat and choose Agent Builder in the agent picker. It is listed only for AI administrators.

  2. Describe the agent: what it is for, who uses it, which records it reads and which it changes.

    Build an agent that helps project managers triage project tasks: it reviews open tasks and changes their priority or status through the task form.

  3. Answer its questions. The forms do not hold the process, so it asks about it: the rules and their exceptions, where each value comes from, what "done" looks like, and two or three requests your users really make. Each question comes with its likeliest answer, to accept or correct. It reads the AI configuration with inspect_ai_config, the models, and the forms involved with inspect_process, and asks what a Java step does when a form runs one.

  4. Review the draft. It shows everything before saving: the agent’s configuration and prompt, the skill’s instructions, its procedures, and any new tool.

  5. Approve each save. Every save asks on its own card — Create the skill?, Create the agent? — with a note on what it starts as, or on who else a change reaches.

  6. Approve its trials. It runs the saved agent with try_agent on your requests and on an edge case, reads every call it made, and fixes and saves again where one went wrong. See Trial runs.

  7. Finish on the forms. Under AI  Configuration  Agents, review the new agent, enable it, and choose the roles, groups or users who may use it. Review and enable any new tool, and fill any secret it names.

A new agent is saved disabled and shared with no one; a new tool is saved disabled and asking for approval. The builder cannot enable, share or grant anything — those steps are always yours.

What it can change

Record Creates Edits

Agents

Disabled, shared with no one

Any agent but itself; its enabled state and who may use it are kept

Skills

Enabled — a skill does nothing until an agent links it

Any skill but its own; the card names the agents that use it

Tools

SCRIPT, HTTP, ACTION or SYSTEM, disabled and asking for approval

Any of those types but its own; the card warns when what an enabled tool runs changes

Anything else

—

—

It cannot write MCP tools (they come from their server) or client tools (they come from the browser), change who may use an agent, or change itself — its agent, the tools it is given or its skill.

Seeded agents, skills and tools can be edited too. A Reload built-in defaults of the built-in configuration overwrites those edits.

Its tools

Tool Safety Does

inspect_ai_config

Read-only

Lists agents, skills with their procedures, tools, knowledge bases and chat models, with which agents use each. Reads one record in full; an agent’s adds the tool calls refused in its recent chats. Never shows a secret’s value, nor a credential written into a tool’s URL, headers or body.

inspect_process

Read-only

Digests how a model’s forms work, or checks a skill’s procedures against them. See Procedures.

save_agent

Asks first

Creates or updates an agent from the fields of an agent file’s frontmatter. Its answer names the links the agent’s words lead it to but its permissions leave unreadable.

save_skill

Asks first

Creates or updates a skill: instructions, references and procedures, which are checked against the forms before the save — a step on something a form limits needs a when.

save_tool

Asks first

Creates or updates a tool.

try_agent

Asks first

Runs an agent, even a disabled one, on a request, and answers with its reply and every call it made. See Trial runs.

Every one of them refuses anyone but an AI administrator, whatever agent it is linked to. Its other tools — list_models, use_skill, search_knowledge and the ask_to_* tools — are the standard ones. Its guidance is the agent-builder-design skill.

Trial runs

try_agent runs the agent as it would run for a user, with these differences:

  • Every change it makes is undone right after the call, and its approvals are granted. A procedure runs through the form as usual, so its result shows what the form would have done — a value the save cleared included.

  • A SCRIPT, HTTP, ACTION or MCP tool is not run: it may reach a system the undo cannot. Nor is a Studio deploy, undeploy or delete, whose effect on the running application the undo does not reach. A client tool and try_agent are not offered, and a question a form asks ends that call.

  • It runs with your rights. A permission the agent lacks still refuses; a right its users lack does not.

  • A tool saved disabled is not part of it.

A button or action that sends a message or calls another system does so, even in a trial. The approval card says so.

Secrets

No builder tool takes a secret. Where a tool needs a credential, the builder writes a placeholder — Authorization: Bearer ${secret.API_KEY} — and tells you which name to fill in the tool’s Secrets field. save_tool refuses a header or query parameter that looks like a credential and holds a value instead, and inspect_ai_config hides such a value where an existing tool has one. A script is read out as written: keep credentials out of scripts. See HTTP tools.

Tips

  • Say what the agent changes and how. A change the form’s logic decides — a status, a confirmation, a computed total — gets a procedure; a plain field no form rule touches, such as an assignee or a date, is written directly. Lines count too: "add a product to the order, as in the grid" gets a procedure that adds a line.

  • Let it reuse. It checks the AI configuration first, and links an existing skill or tool rather than writing a new one.

  • Give it real requests. The trials are only as good as the requests they run; give the ones your users make, and one that goes wrong today.

  • Try the agent yourself once enabled, before sharing it. When it fails, tell the builder which agent: it reads the calls the agent got refused, fixes every cause in one save, and tries the request again.

  • Mind the linked models. Reading a field that links to a model the agent may not read refuses the whole call: an agent that matches tasks on their tags needs Tag as well as ProjectTask. The builder warns about the links its own instructions name, one or two levels deep.

  • After an upgrade, ask it to check a skill’s procedures: inspect_process reports what the new forms would stop.