Build an agent

Create an agent, write its instructions and schemas, choose its model, and give it tools with or without approval.

You build an agent in the agent builder: three tabs, Definition, Tools and Versions. The examples on this page build an Invoice triage agent that reads the accounts payable policies and posts invoices that are within policy. Before you start, finish Set up Agents. You need tools.create and tools.edit in the workspace. Create an agent# Open Agents and select Agents in the menu. Select New agent. Enter a Name. The Key is filled in from the name; you can change it. A key starts with a letter and uses lower-case letters, digits and hyphens. It cannot be changed later. Select Create agent. The builder opens on the new agent, marked Draft. Write the definition# On the Definition tab, write the Instructions: what the agent is for, which tools to use when, and what to return. Name the tools as they appear on the Tools tab. Under Model, choose the model binding, for example agent:default. The list shows the workspace's enabled models of purpose agent. Optional: under Inputs and outputs, enter an Input schema and an Output schema as JSON Schema objects. The input schema describes what a caller passes in; the output schema is what the agent's answer must match. A field that is not valid JSON shows the error under it, and you cannot save until it is fixed. A dot next to a tab name means it has unsaved changes. Select Save changes. If someone else saved the agent while you were editing, a banner offers to reload their version or keep editing yours. Add tools# The Tools tab has two cards: Selected (the tools the agent may call) and Add tools (everything in the workspace it could call). Select the Tools tab. Under Add tools, select the check box of each tool. Use Search to filter. Tools are grouped by kind: Processes: the workspace's processes (except the Agent Runner). The agent starts the process with the arguments it chooses. Vector stores: a search of a workspace vector store. See Vector stores. Check each selected tool's settings: The name in bold is the name the model sees, for example Invoice_Processing for the package Invoice.Processing. Use it in the instructions. The risk badge: a vector store search is Low risk; anything else is Unknown risk. Approve each call: for Unknown risk tools it is always on and cannot be switched off. For a vector store you can switch it on. Select Save changes. To remove a tool, select × next to it. NoteA tool that needs approval makes the run stop and wait until someone approves or rejects the call on the Approvals page. See Runs and approvals. Limits on a run# Each agent has guardrails. The defaults are: Guardrail Default Model calls per run (maxSteps) 12 Tokens per run (maxTokens) 50,000 Run time (timeoutSeconds) 900 seconds Answer checked against the output schema (outputValidation) schema The run page shows Step N of the step limit. Guardrails, and a list of blockedTools the agent may never be published with, are part of the agent definition; change them through the API (PUT /api/v1/tenants/{tenantId}/workspaces/{workspaceId}/agents/{key} with the full definition and the current revision). Next steps# Test and publish an agent

Create an agent

Write the definition

Add tools

Limits on a run

Next steps