Your first agent
Agents are the unit of work in Exolvra. This page walks you from an empty dashboard to a working specialist — system prompt, tools, and your first conversation.
Decide what kind of agent
Exolvra has two kinds of agents, and they are not the same thing:
- Specialist — autonomous. Picks up work from issues, executes tools on its own schedule, writes to the data store, and collaborates with other agents. This is the kind you want if you’re building a team.
- Chatbot — interactive only. Waits for a user message, responds, waits again. Never picks up background work. This is what you want if you’re embedding a support or FAQ bot on a website.
For your first agent, build a specialist. Chatbots have their own creator at /bots/new — see Dashboard → Bots when you’re ready.
Create the agent
Open /agents in the dashboard and click New Specialist. You’ll land on the Agent Creator form with five sections:
1 — Identity
- Name — a short, memorable handle. Lowercase, no spaces:
research-analyst,code-assistant,designer. This becomes the agent’s id everywhere — in chat, in the session list, in inter-agent messages. - Display name — a human-facing label, free-form: “Research Analyst” or “Alex the Designer”.
- Description — one sentence explaining what this agent is good at. This is what other agents see when they consult the team roster, and what the Project Manager reads when delegating work. Write it like a job posting, not a biography.
- Icon — an emoji. Pick one that’ll read at small sizes in the sidebar.
2 — Personality
The personality field is the agent’s system prompt. This is the most important thing you’ll write, so don’t skimp — a good personality is specific, opinionated, and 5–15 sentences long. A weak one is vague and three sentences long.
A good personality answers four questions:
- Who are you? — “You are a senior research analyst with a background in competitive intelligence.”
- What do you do well? — “You synthesise information from many sources into a single clear brief. You cite your sources. You resist speculation.”
- What do you avoid? — “You never fabricate quotes or statistics. You never save findings without source attribution.”
- How do you communicate? — “You write in short paragraphs. You lead with conclusions. You use bullet lists for parallel findings.”
If you want a library of starting points, open Personality from the dashboard — it has preset SOUL files you can copy into the creator as a baseline.
3 — Tools
Tools are the agent’s capabilities. Check the boxes for the ones this agent needs. Pick the smallest set that lets it do its job — over-granting tools makes agents slower and more expensive, and adds attack surface.
Common bundles:
| Agent kind | Recommended tools |
|---|---|
| Researcher | web_search, web_fetch, data_store, memory, think |
| Writer | data_store, memory, file_store, think |
| Coder | file_system, shell, web_fetch, data_store, think (or use a CLI adapter — see CLI adapters) |
| Project manager | project, task_board, send_email, sessions_send, memory |
| Analyst | data_store, web_search, file_store, think |
You can change the tool set any time. If an agent fails because it can’t do something, add the missing tool from the edit page.
4 — Model
Pick the model the agent will use. Leave it blank to inherit the instance default from Config → AI Providers. Override it when a specific agent needs a bigger model (opus-class for deep reasoning) or a cheaper one (haiku-class for quick assistant work).
5 — Keywords
Short list of lowercase words that describe what this agent is for: research, competitive, market. When auto-dispatch is set to keyword matching, Exolvra uses these to find a best-fit agent for an unassigned issue. If you’re using the default PM-delegated dispatch mode, you can leave this blank — the PM reads the description instead.
Click Create agent. You land on the agent detail page.
Test it in chat
Open Chat from the sidebar. In the agent dropdown at the top of the page, pick the agent you just created. Type a message that matches its specialty — for a researcher, something like “Summarise the three most common pricing models for SaaS project management tools.”
What you should see:
- The agent’s avatar and name appear in the header
- Your message sends, and the agent starts streaming a reply
- If the agent uses a tool, a collapsible tool-call card appears inline showing the arguments and the result
- When the agent is done, the reply renders as markdown with your budget updated in the footer
If the agent just chats without using tools, the personality is probably too loose. Edit it to explicitly instruct the agent to use specific tools: “Always use web_search to gather sources before writing. Always save findings to data_store with source URLs.”
If the agent uses tools but produces shallow results, the personality probably doesn’t specify what “done” looks like. Add a quality bar: “A good research brief has at least five sources, a summary of tradeoffs, and a recommendation.”
Assign it an issue
Chat is fine for ad-hoc work. The real pattern is:
- Create a project from Projects → New project
- Create an issue inside that project describing the work
- Assign the issue to the agent you just built
- Watch the agent execute on its own, stream tool calls, write to the data store, and mark the issue complete
The agent runs on its heartbeat — roughly every 30 seconds — and picks up assigned issues as long as it has capacity. Issues vs. ad-hoc chat is the core workflow; learn more on the Issues and Projects pages.
Next
- Your first project — the capstone: hand an agent a goal, watch it break down and execute
- Agents and chatbots — the full concept, including when to use each kind
- Orchestration patterns — seven ways to make multiple agents coordinate