Agents

In Orbi an agent is the definition of a team member. It carries these.

#Ready-made templates

When you create a new agent you can start from one of nine ready-made templates. A template fills a name and a brief into the form, and you can write over it freely.

Content and research

Sales

Quality and measurement

You can use these as they are, edit them, or create a new agent from scratch.

Every agent has a name, an optional title and a required short description. The name is the identity, meaning it is what you use when you call the agent in text (@agent.<name>). The title is only there to be seen and it helps the team recognise the agent. The description answers the question "which job goes to this agent". When Orbi decides who gets a piece of work, it never reads the agents' briefs, only this description. That is why a new agent cannot be created without a description of at least 10 characters. An older agent saved without one shows a warning on its page, and lists show it as "(no description)". Write one sentence about what it does and save, so work can be handed to it.

Do not write how the agent should behave into the description, because behaviour is the brief's job. Writing instructions into both leads, over time, to two definitions that contradict each other.

The name and the title stand together everywhere the agent appears. You see them in the team list, on the card in the flow canvas, in the signature under a comment, in the assignment picker and in the suggestion list that opens when you type "@". The description shows up when you hover over it. While you edit the agent, the small preview box at the bottom of the form shows you how this will look as you type.

Why you should set the Reviewer up as a separate agent. It is no use for the agent that produced a piece of work to check its own work, because it carries the same assumptions. When a review is needed, the orchestrator first picks a reviewer agent defined in the workspace IF there is one. If there is not, this step is skipped.

On top of these, Orbi (the Orchestrator) is created automatically in every workspace. Its role is not to do the work but to hand the work out, and the details are in The Orchestrator.

If several of your agents carry almost the same brief (say, coding agents that each work on a different repository of the same project), you can group them into a squad and manage the shared instruction in one place. Details are on the Squads page.

#Agent Builder: set one up by talking

You do not have to write the agent by hand. The Builder panel on the left of the detail page is a build partner that works through conversation. You describe what you want in your own words ("I want an agent that reads incoming support emails and opens complaints as tasks"), the Builder asks about the decisions that shape the job, and it writes the draft live into the form on the right. It fills in the name, the title, the short description, where it runs, the model and the connection access, and the brief is written in the editor in front of you.

You answer the questions by clicking. When the Builder cannot write a good agent without knowing something, it opens a tabbed card for you. Every question carries its options and what each option means, such as the difference between "let it only prepare a draft" and "let it send the message itself". If none of them fits you can say Other and write your own answer, or leave the decision to the Builder with You decide, in which case it writes down the assumption it made.

Answering the questions is not compulsory, but it pays off, because an agent is only as good as the definition you give it. What the Builder asks about is exactly what makes that definition clear, namely when it steps in, how far its authority goes, what it does when data is missing and where it writes the result.

You can show instead of describe. The attach button in the message box adds a screenshot or a document, and you can also point at a file you uploaded earlier by typing "@" and its name. The Builder sees the image you attached and reads the text of the document, so you do not have to describe the process diagram in your hand or the brief you wrote somewhere else. Sending only the file, with no text at all, works too. If there is a case where it cannot read the file, for example a scanned document with no text layer, it tells you instead of guessing the content.

Here is what to know.

• The Builder does not save. When the draft is ready you review it, correct it by hand if you want, and you are the one who presses Save.
• The conversation belongs to the agent and it persists. After you save, and on another day, you carry on for the same agent from where you left off, and your teammate sees the same conversation. For a new context use Clear the chat, and the form does not change.
• The Builder can only suggest integrations that are actually connected in the workspace. If a connector is missing it says "an admin has to connect it first" rather than making one up.
• The Builder is not an agent. It does not appear in the team list, it does not take a seat and it cannot be @mentioned.
• Every Builder message is a normal AI run and it comes out of your credits.

Inside the prompt you can point at tools with @tool ("when you spot a complaint, use @tool.create_task"), and when you type "@", tools show up in the suggestions too. This makes it clear which tool the agent should use in which situation, and the Builder uses the same mentions in the prompts it writes.

In the tool suggestions and on the tool chip in written text, the icon says where the tool comes from: a wrench is one of Orbi's built-in tools, and a tool of a service you connected shows the service's logo (a plug when it has none) and the connection's name. A connected service's tool is written with its connection, for example @tool.design.post_create, so the mention always points at the right tool even when a built-in tool or another connection carries the same name, and the tool is in the agent's list from the start of the run. Write only @tool.design and the agent takes it that the job uses this connection and picks the tools itself (Tools). If you type a name that is not in the list yet, the chip does not break; hovering it says the name is not in the tool list.

#Avatar

You upload an agent's avatar on the Agents page in the left menu, by clicking the avatar in the agent's detail. It accepts PNG, JPG, WebP or GIF, 5 MB at most. You can also pick one while creating a new agent, and the image is uploaded after the agent is saved.

If you do not upload one, the agent uses a face derived from its name. That face is the same on every screen and does not change unless the agent's name changes, so you do not have to upload an avatar. Agents can already be told apart on the board.

You can also draw the agent's avatar. The Draw button under the avatar opens the same generator that people use for themselves, where hair and head, hair colour, expression, beard, glasses, skin, clothing and background colour are picked one by one. The options are shown as small faces, so you just click the picture. You can draw one while creating a new agent too, and the choice is applied when the agent is saved. When you save a face you drew, any image uploaded earlier is removed, because an agent's avatar is always the most recent choice. The options are deliberately narrow. There are no negative faces such as angry, fed up or frightened, because a teammate's face should not load emotion onto you. In Orbi it is the colour of the card that tells you whether something is going well or badly, not the agent's face. The colours are limited to the system's palette as well, so avatars sitting side by side do not compete with each other.

Unlike user avatars, agent avatars belong to the workspace. An agent lives inside a workspace, so its avatar is that workspace's shared property and anyone who can edit it can change it.

#The identity block and the three tabs on an agent page

Opening an agent shows its identity at the top: avatar, name, title, short description. This block is fixed — it stays visible no matter which tab you're on, and switching tabs does not make it disappear.

Below it are three tabs.

Definition is what the agent does: its squad (if it belongs to one, the shared instruction shows up here too) and its brief.

Work is where and how it runs. At the top you pick where it runs (inside Orbi, or in your environment), and that choice shapes the rest of the tab. For an agent that connects from outside, its repository, base branch and the devices sharing that repository sit right below it. For an agent that runs inside Orbi, the model choice lives here. Connection access and the connection status are on this tab too; setup and tokens live on the Tool access tab of your profile.

Activity is what the agent did.

There is a single Save button and it sits at the top of the page, so whichever tab you type in, one save covers all of it. If a tab holds unsaved changes, an amber dot appears next to its name, so switching tabs does not make you forget what you wrote. The identity block (name, title, description, avatar) does not belong to any tab, so it never triggers that dot — it's always visible already.

While creating a new agent there are no tabs; the whole setup flows on one page below the identity block.

#Where it runs: inside Orbi, or in your environment

Every agent has a place where it runs, and you pick it at the top of the Work tab.

Runs inside Orbi (the default). When a task is queued, Orbi does the work with its own model. Researcher, writer, editor and analyst are the teammates that can do their job with Orbi's tools. Every agent up to now works this way.

Connects from outside. The work is done by a client in your own environment, such as Claude Code, Cursor or a program you wrote yourself. The typical case is a developer teammate, because it has to read and change code, open a branch and submit a PR, and that happens on your device rather than on Orbi's server.

When you assign a task to this agent and queue it, Orbi does not run it with its own model. The card waits in the queue marked "waiting for the client", and when the client connects it takes the task itself, does it, writes its comment and moves the card to review.

That is why an agent that connects from outside shows no model setting and no external MCP access setting, because both are read while Orbi is running an agent. Here it is not Orbi that runs but your client, so you decide in your own environment which model and which tools it works with.

You can change the place it runs later, but it costs something. Switching a saved agent to "runs inside Orbi" and saving clears its repository setting; switching it to "connects from outside" clears the model choice. Both are cleared because both are meaningless in that mode. The moment you change the choice, what you would lose is written under the selector, so you see it before saving.

The brief is still delivered. You do not have to write a brief for an agent that connects from outside, but if you do it is not wasted. The moment the client connects, Orbi sends it its own definition as it is, and the client adds that text to its own instructions. So the sentence "in Orbi, Claudia is this" holds in Claudia's session in her own environment as well.

Know that this is not a forced override. The client's own rules stay in force, and when they conflict the agent is expected to write that under the card rather than quietly pick one. There is one note on timing. The definition is sent at the moment the client connects, so if you changed the definition, a running client has to refresh its connection to see it.

Why can it not be both? When a card is queued the system has to know who will do the work. If both were open, the same job could be done twice or not at all. If you need both, create two separate agents, because that is an honest separation.

#How to set up an agent that connects from outside

1. From the left menu, go to Agents → New agent.
2. Give it a name, pick "Connects from outside" and press Create. With this option the brief (system prompt) is not required, because Orbi is not running the agent and you are the one telling the client in your own environment what to do.
3. Once you save you are on the agent's detail page. The Connection section on the Work tab only shows the connection status: whether a client is connected, or when it was last seen. Setup and tokens are not on this page but on the Tool access tab of your profile; the Open Tool access button in the section takes you there.
4. The setup guide on the Tool access tab is a set of client cards (Claude Code, Claude, Cursor, VS Code, Other client) and gives only Orbi's address; for Claude Code the ready claude mcp add … command has a copy button next to it. Paste the command into your client and press its connect or Authenticate button. Orbi's consent screen opens in the browser; pick the workspace and this agent, then press Allow.

The connection runs with the agent's identity. Every comment it writes on the board appears under that agent's name, not yours. That keeps the answer to "who did this work" clear on the board.

If you are connecting a client without a browser (a script, a scheduler), you create a secret token: press Create token on the Tool access tab of your profile and pick this agent under Acts as. The list shows every agent that runs outside Orbi (code agents with a repository included) with their avatars and titles, and you can search it by name. Role (default member), name, validity (default 90 days), read-only and closed spaces are chosen in the same dialog. The token is shown once only, so copy it before you close the dialog; the setup steps come with the token in them.

Tokens that act as an agent are created by the Admin only. The Access tokens list on the Tool access tab shows, in the workspaces where you are an Admin, every agent token including those other admins issued: the ones you issued are under My tokens, the rest under Other people's. You can revoke any token you see there. An agent token you issued, or authorized on the consent screen, can still be revoked by you after you stop being an Admin. The reason is that an agent is a shared resource rather than a personal one. Everyone on the team can use the same agent, so its identity is the team's responsibility. Your own personal tokens are separate from this and nobody can see them, as described in Collaboration.

If you later change where an agent runs, its existing tokens are revoked on their own. An agent marked "Runs inside Orbi" cannot be connected to from outside, and no token is left in the list looking live while it no longer works. If you open the agent to the outside again, you create new tokens.

The row of an agent token that another admin issued names who issued it, and opening the token shows the same under Issued by. That detail is tied to a security rule: when a member leaves or is removed from the workspace, the agent tokens that person issued are revoked on their own. A client left running on that person's device can no longer write to the board under the agent's name. Tokens issued for the same agent by another admin are left alone. Older tokens carry no issuer; reviewing and reissuing those is your call.

An agent token with the Old token badge has no person recorded behind it: neither who issued it nor who authorized it on the consent screen is known. Such a token sees Genel and the open spaces but cannot reach closed spaces, and no closed space can be chosen for it, because the token's person makes that choice. When the agent asks for a closed space by name, the error it gets says so. The fix is to create a new token and revoke the old one.

Picking a role is up to you. You also pick the agent's role while creating the token. The default is member, and for a client that will only watch the board, viewer is the better fit. Do not grant more authority than is needed.

Closed spaces are chosen per token too. A token sees Genel and the open spaces. It sees a closed space only when it is chosen with Choose closed spaces on the token's row. The person who created the token chooses, among the spaces they are a member of. If that person leaves the space, the token loses it at once. Opening a closed space to a token is written to the Audit tab.

#What happens if the task is not taken

If its client is not running (the device is off, the program is not open) the card waits in the queue. That wait is not endless. If nobody takes it within 6 hours the card moves to the error state and the reason is written to the activity log. That way no card is quietly forgotten.

The same patience applies to a client that did take the work and then went quiet. If the card makes no progress at all for 6 hours after it moved to the running state, it is moved to the error state as well. The two limits are deliberately equal, because "nobody took it" and "whoever took it went silent" are the same problem for you.

You can see whether the agent is connected without waiting. The mark on a queued card says whether its client is online, offline (with the last seen time), has never connected, or whether the agent has no token at all. When you open the card the same information appears together with how many hours are left before it moves to the error state if nobody takes it. Once the client has taken the card, the mark shows the name of the device doing the work, and says so if that device's heartbeat stops. The connection status, with the last seen time, is also in the Connection section of the agent page.

You are also told at the moment you queue the card. If the agent's client is not connected right then, Orbi asks for a short confirmation and tells you the card will wait until the client starts. If no token has been created for the agent yet, the message is firmer, because nobody can take the work. The confirmation does not stop you from queuing the card, and if you are about to turn the device on, queuing the card now is the right move. The same confirmation appears when you assign a queued card to this agent and when you open a new card straight into the queue.

#All agents are workspace-wide

There are no personal or private agents. The reason is that anyone should be able to assign any agent to a task. The consequence is that when you change an agent's brief you affect everyone who uses that agent. If you want to try an experimental prompt, create a new agent instead of editing the existing one.

An agent open to everyone does not make the data open to everyone. The agent works in the space of each job: on a card or flow in a closed space it writes only to that space and cannot carry the space's data to Genel, to another space or to a connection nobody chose. Working on a job in another space, the same agent cannot read the closed space.

#Writing a good brief

The brief (system prompt) is the single most important thing that decides an agent's quality. Here is the pattern that works.

You are a senior market researcher.

HOW YOU WORK
- You tie every claim to a source; you do not write a claim that has none.
- You give figures together with their date ("as of Q3 2025").
- Where you are not sure you do not guess; you write the uncertainty down plainly.

OUTPUT FORMAT
- Markdown; at most three heading levels.
- A "Sources" list at the end of every section.

WHAT YOU DO NOT DO
- You do not use marketing language.
- If there is no finding you leave the section empty; you do not invent one to fill it.

Three rules work in practice.

1. Write the role, the behaviour and the output format separately. "Be a good writer" does not work, while "keep every paragraph to three sentences at most" does.
2. Write down what it will not do, too. Models tend to fill gaps by default, and the sentence "you will not make things up when there is no finding" makes a measurable difference.
3. Name the tool. A sentence such as "when you need it, look at the existing records with search_records" raises the chance that the agent picks the right tool.

#Trying it without saving

Once the brief is written, you do not need to open a real card to see how the agent behaves. Write a sample request into the Try it card right below the brief and press Run. The agent produces a single answer with the brief as it stands in the form, and the answer appears in the same card. You do not have to save to change the brief and try again, because the card uses the current state of the form every time.

Nothing lands on the board during a trial, so no task, record, file, comment or conversation is written. The agent can only use read tools (search, reading records and tasks), so you see its "look it up, then answer" behaviour while it cannot change anything. If it would have to write something to fulfil the request, it says what it would do in a real run and shows what it would write. The model that was used is shown under the answer.

A trial is a real model call and, like every other run, it is charged to your credits. An agent that connects from outside cannot be tried here, because its own client runs it, not Orbi.

#Duplicate

You can duplicate an agent, brief, model and tool access included — if you want a second variant with a small difference, you do not have to write it from scratch. The Duplicate button sits in the page's top bar, next to Save (in a quiet tone); Delete agent sits in the same bar, in red. Neither is shown for the orchestrator agent.

#Choosing a temperature

#Reasoning effort

Reasoning effort is how much the model thinks before it answers: Auto, Low, Medium or High. You pick the agent's default on the agent page's Work tab, under Settings, right below the model choice. In a chat the button next to the model picker changes it per message, and the Reasoning effort row in the card detail changes it per card; the chat remembers your pick for that conversation. Auto leaves the decision to the next layer: a message and a card use the agent's setting, and the agent uses the model's own level. More thinking can give better answers on hard work, but it is slower and spends more tokens. A model with no effort setting ignores the choice. A code card running on a device takes its level from its own run settings.

#Seeing how an agent worked

When a task is finished, the card's Trail tab shows, for every cycle, which agent ran with which model, whether the fallback stepped in, whether there were sub-agent runs, and how many tokens were spent. If an agent is not producing what you expected, diagnosis starts here.

#How agents reach the outside world

Agents use three layers of tools. There are in-process internal tools, zero-setup hosted MCP (web search and page reading) and the external MCP servers you connect. Details: Tools and integrations.

The orchestrator sees every tool, while directly assigned agents and sub-agents get a set narrowed down by the least privilege principle. This keeps an agent from touching something outside its scope by accident.

You narrow it in two stages. In the Connection access section of the agent's detail page you first tick which connections it can use. Then you can open a connection's card, see its tools one by one and give the agent only some of them. That way, of two agents connected to the same email account, one can only read while the other can send.

If you tick no tool at all, the whole connection is open and tools added later arrive on their own. If you make a selection, only what you selected arrives. A tool switched off at workspace level cannot be opened to any agent, and the list says it is closed.