Agents: build a custom assistant
An agent is a saved configuration: instructions, a model, an avatar, starters, capabilities, knowledge and connectors. Build one in a few minutes, test it beside the form, then share or deploy it.
Updated October 2026Agents1 of 4
Short answer
Create an agent
- Step 1
Start a new agent
Go to/agentsand choose New agent. The builder has three sections: Create, Configure and Deploy. - Step 2
Describe it, or fill in the form
In Create, tell the builder what the agent should do, who it is for and how it should sound; it drafts the name, description, instructions, starters, capabilities and knowledge into Configure and marks each field Drafted by builder. Drop documents into the chat and they upload as knowledge when you create the agent. Prefer the form? Open Configure and type. - Step 3
Review the draft
Each drafted field shows Applied to Configure with Undo; Undo all reverts everything. A field you edit yourself is kept as you wrote it, even if you ask the builder for more. Trimmed or skipped suggestions are listed as notices (for example a capability left off because setup is required). - Step 4
Talk to it before you save
As soon as a name and instructions exist, the Live draft preview lets you message the agent with your unsaved instructions and knowledge. Start over resets the preview. - Step 5
Create
Nothing is saved until you press Create (or Save on an existing agent). The header then shows the agent's name with a Live badge.
The builder, field by field
| Field | What it does |
|---|---|
| Name | The display name. Required before you can attach files. |
| Description | A short summary shown to users before they start a conversation. |
| Instructions | What the agent does, how it behaves and what it should avoid. Conversations can reveal part or all of the instructions. |
| Identity | Speaks as Akili (default) adds Akili's standard self-description after your instructions; Own persona only and Own persona, no Akili greeting or identity drop it. |
| Model | Default (inherits from chat) uses whichever model is selected at chat time; or pin one model for every conversation. |
| Avatar | Upload avatar image sets a picture; Remove avatar clears it. |
| Conversation starters | Suggested prompts shown at the start of a conversation. Add starter adds a row. |
| Rich replies | Cards and quick replies the agent may show in webchat: you write the card, the model picks the moment. |
| Capabilities | Web Search, Image Generation, Canvas, Code Interpreter & Data Analysis, Fetch web pages and Places, each with a readiness pill. |
| Knowledge | Uploaded files and linked knowledge bases the agent searches while it answers (see the next page). |
Capabilities
Capabilities are the tools the agent may call. Each one carries a readiness pill: Checking while Akili asks the platform, then Ready, Setup required or Restricted, with the reason spelled out, for example A platform administrator must bind an enabled image model to the image role or Your organization has disabled Maps. The assisted builder never turns on a capability that is not ready.
| Capability | What it allows |
|---|---|
| Web Search | Search the web for up-to-date information. |
| Image Generation | Generate images. |
| Canvas | Create and edit documents and code in the artifacts panel. |
| Code Interpreter & Data Analysis | Run code and analyze data in a sandbox. |
| Fetch web pages | Read pages at URLs, optionally limited to an allowlist of domains. |
| Places | Search places and routes; needs Maps enabled for the organization. |
Mandates
A mandate is what the agent may commit to on your behalf: Purchase, Refund, Book, Share data, Sign or Transfer. Every committing tool call is checked against the agent's mandates before it runs; without one, every committing action asks you first.
- Grant a mandate with a currency, a per-action cap, a monthly cap, an Ask above threshold, a Valid until date, the counterparties it applies to (any, a named Akili agent, or a name or URL) and the liable party (your organization or you).
- Narrow lowers a cap or ends it earlier; a narrowed mandate is a new version and the old one is kept for its receipts. Revoke ends it; receipts under it are kept.
- Receipts. Every committing call leaves a receipt signed with the agent's key, kept for seven years, with the outcome Committed, Approved or Denied, and Copy JSON for your records.
Test, save and the Live badge
Test agent opens a preview chat with the current form, so you can try instructions before anyone else sees them. Save writes the form; the toast reads Agent saved. The header badge reads Live for a saved agent and Draft for one that has not been created yet. Next to it, the visibility reads Only me, Anyone in org or Public link; see Share and publish an agent.
Export and import
Export a zip
Export agent, from the agent's menu on the Agents page, downloads agent-<name>.zip. The archive holds an agent.json manifest with the name, instructions, capabilities and settings, and the knowledge files.
Import a zip
Import agent from zip file on the Agents page creates a new agent from an archive. The manifest must be valid and carry a name; the import rejects an archive without agent.json. The toast reads Agent imported.
Where agents appear
- Sidebar. My Agents lists the agents you own or can use; opening one starts a chat at
/a/<agentId>, which stays in your chat history like any other conversation. - Home page. The Ask an agent start card names your agents and opens the one you pick.
- In the chat. An agent's chat shows a Tools line with its connected servers and knowledge sources, so you can see what it can reach.
- Elsewhere. A webchat channel puts the agent on your website, the Inbox shows its visitor conversations, and the marketplace lists it for other organizations; all three are on the next pages.
Good to know
- If the builder chat is unavailable: the Create tab says so and Configure still works; administrators bind a model for it under Platform settings → Models.
- If a starter is cut: the builder keeps the first few starters and says Kept the first {max} starters; add more by hand or ask it to suggest three more.
- If you want the agent to act without asking: grant a mandate with caps you are comfortable with; Ask above keeps the question for anything larger.
- If the agent should use skills: the Skills section of the builder appears when skills are enabled for your workspace; see the Skills guide.
Frequently asked questions
Is there a draft I can keep editing without affecting people using the agent?
The builder works on a draft of the form: nothing reaches the saved agent until you press Save (or Create for a new one). Once saved, the change is live for everyone the agent is shared with. Export a zip before a large edit if you want a copy to return to.
Can I see earlier versions of an agent?
Not in the builder today. An exported zip is the way to keep a snapshot: it contains agent.json with every setting plus the knowledge files, and Import agent from zip file restores it as a new agent.
Which model does an agent use?
The one you pin under Model, or, with Default (inherits from chat), whichever model the person chatting has selected. Pinning a model is the way to make the agent behave the same for everyone.
Why is a capability marked Setup required or Restricted?
Setup required means the platform is missing something: for example no image model is bound to the image role, or Maps is not configured. Restricted means a platform administrator or your organization's policy has turned the capability off. The pill's text names the fix.
Do I need a plan for the assisted builder?
The Create tab's builder chat is a plan feature (agents.builder_assist). Without it, or if no model is bound for it, the Configure form still works and your draft is safe.