Create and edit an agent

You create an agent with the Create agent wizard on Build › Agents, change it on its Edit agent page, or bring one in from a file with Import YAML. Each way ends with the same thing: an agent file that can be exported, reviewed and promoted.

Who can open it

Role	What they can do
Admin	Create, import, edit and save agents.
Builder	The same as an Admin.
Auditor	Cannot create, import or edit. Reads every agent on its page.
Reviewer, End user	Cannot open it.
Platform admin	Everything an Admin can, in any tenant.

Before you start

• A chat model. The tenant needs at least one deployed chat model. Without one, the Behavior step reads This tenant has no chat model deployed yet, so an agent has nothing to answer with. and links to Deploy a model. See Deploy a model.
• Collections, if the agent answers from documents. You can add them later. See Collections.
• A tool server in service, if the agent calls tools. You can grant tools later. See Tools.
• Skills, if the agent follows written procedures. See Skills.

What you see

The Create agent wizard

The wizard has six steps, in order. Next checks the step before moving on; Back keeps what you entered. Leaving before Create agent warns that what you entered is lost.

Step	Fields
Identity	Name; When should this agent be used? (tagged Routing key), with a character counter.
Behavior	Model, Instructions, Temperature.
Knowledge	A checkbox per collection (with its database and chunk count); Chunks per answer.
Tools & skills	Toolkit (a server picker) with the tools that server offers; the Skills list; Effective tools.
Limits & approvals	Tool calls per run, Model calls per run, Tokens per run, the cost estimate, and Which tools need approval.
Review	The agent file that will be saved, with Copy the YAML.

The Edit agent page

Edit agent shows the same fields as sections on one page: Identity, Behavior, Knowledge, Tools & skills and Limits & approvals. A bar at the bottom reads Unsaved changes or Everything is saved, with Discard (or Back when nothing changed) and Save. Leaving with unsaved changes asks you to confirm.

On a platform-shipped agent every field is disabled and the page opens on Shipped with the platform. See Platform-shipped agents.

What you can do

Create an agent

1. Open Build › Agents and choose Create agent.
2. Identity:
   1. Enter a Name.
   2. Under When should this agent be used?, write one or two sentences that say which questions belong to this agent. Other agents read this to decide whether to hand work to this one; it does not change how this agent behaves.
   3. Choose Next.
3. Behavior:
   1. Choose the Model. The list holds the chat models the tenant has deployed.
   2. Write the Instructions. Only this agent reads them.
   3. Set the Temperature (0 to 2; default 0.2).
   4. Choose Next.
4. Knowledge:
   1. Select the collections the agent grounds its answers on.
   2. Set Chunks per answer: how many passages are retrieved for each answer (1 to 20; default 6).
   3. Choose Next.
5. Tools & skills:
   1. Under Toolkit, choose a server. Olympusx AI asks it what it offers (Asking the server what it offers…) and lists its tools, each tagged read or write, with Allowed for this agent · n of total.
   2. Select the tools this agent may call. Repeat for other servers; tools chosen on other servers are listed below the picker.
   3. Select the skills the agent may use, and read Effective tools to see how each skill narrows the tools.
   4. Choose Next.
6. Limits & approvals:
   1. Leave Tool calls per run, Model calls per run and Tokens per run blank to use the platform defaults, or enter a positive number.
   2. Read the estimate: At most a cost per run, at the dearer of this model’s two rates, with the token ceiling.
   3. Under Which tools need approval, set each write tool to Held until a person approves or Runs without asking.
   4. Choose Next.
7. Review: read the file that will be saved, then choose Create agent.

Olympusx AI opens the new agent’s page with Agent created. If the agent was created but its tools or skills could not be saved, the message reads Agent created, but not all of it was saved, with the reason; set them on the Edit agent page.

Write the routing key for another agent to read

A short routing key routes better than a long one. When the description you type shares words with another agent’s, a warning names that agent: Another agent claims the same territory. It is a warning, not a refusal, but an agent choosing between the two will pick inconsistently.

Grant tools and choose which ones wait for a person

Registering a server grants nothing. An agent may call only the tools you select for it, on servers that are in service.

• A tool is read when its server declares that it changes nothing; every other tool is write.
• When you select a write tool, it starts as Held until a person approves. A read tool starts as Runs without asking. You can change either.
• A held call waits for an Admin or a Reviewer in Approvals. Approving runs the tool; rejecting runs nothing. See Human approval.

The same tool can be free for one agent and held for another: approval is set per agent, per tool.

Edit an agent

1. Open the agent’s page, open the menu and choose Edit.
2. Change any field. On the edit page, Which tools need approval lists every granted tool, read and write.
3. Choose Save.
4. If an assistant publishes this agent, This agent is published names it: the change takes effect for its users the moment it is saved. Choose Save to confirm.

Olympusx AI returns to the agent’s page with Agent saved. If the new routing key overlaps another agent’s, a message names it.

Import an agent from a file

1. On Build › Agents, choose Import YAML.
2. Paste the file into Agent file (YAML).
3. Choose Import YAML.

Olympusx AI matches servers, skills, collaborators and collections by name. A name this tenant does not have is refused, and the answer lists every missing one; nothing is created. The import is also refused when an agent with the same name exists (change metadata.name), when the file names a model this tenant has not deployed, or when the model cannot call tools and the file grants tools, skills or collaborators.

The agent file

Export YAML produces this file, Review shows it, and Import YAML reads it:

apiVersion: olympus.olympusx.ai/v1
kind: Agent
metadata:
  name: Claims triage
spec:
  description: Questions about the status of an open insurance claim.
  model: <chat-model>
  instructions: |
    Answer from the claims collection. Quote the claim number.
  params:
    temperature: 0.2
    topK: 6
  ceilings:
    maxToolCalls: 10
  knowledge:
    - claims-handbook
  tools:
    - server: claims
      tool: get_claim
    - server: claims
      tool: update_claim
      requiresApproval: true
  skills:
    - escalate-a-complaint
  collaborators:
    - Policy questions

An export also writes exportedAt, exportedFrom and revision under metadata; an import ignores them. A ceiling left out uses the platform default. The file never carries a credential.

Limits

Field or rule	Limit
Name	1 to 80 characters; unique in the tenant.
When should this agent be used?	At most 280 characters.
Model	Required; a chat model this tenant has deployed.
Temperature	0 to 2, in steps of 0.1. Default 0.2.
Chunks per answer	1 to 20. Default 6.
Tool calls per run	A positive number, or blank for the default of 20.
Model calls per run	A positive number, or blank for the default of 25.
Tokens per run	A positive number, or blank for the default of 200,000.
A model that cannot call tools	The agent can answer, but cannot have tools, skills or collaborators. Saving with any of them is refused.
Imported file	At most 256 KB.

A run that reaches a ceiling stops and says which one it reached. The answer so far is kept, and no tool is interrupted half-way.

When it does not work

What you see	What to do
The model is not a chat model this tenant has deployed, so this agent cannot answer.	The model was undeployed. Choose another in Model, or deploy it again.
The model cannot call tools	Remove the tools and skills, or choose a model that can call tools.
The server did not answer	The tool server is unreachable. Choose Try again, or check it on its page in Tools.
No tool servers are in service in this tenant.	Register a server, or put one back in service, on Tools.
The agent was not imported	Read the reason: it lists each missing name, or the field that was refused.

Related

• Agents
• Collaborators
• Preview and test
• Tools and Skills
• Human approval
• Keys, budgets and metering