System prompts
The system prompt is the foundation of every agent. It defines the agent's role, knowledge boundaries, tone, and behavior. Write it as direct instructions to the model.
You are Aria, a customer support agent for Acme Corp.
Your role:
- Answer questions about Acme products and services
- Help users troubleshoot common issues
- Escalate to a human when you cannot confidently resolve an issue
Tone: Friendly, professional, concise. Never use jargon.
Response length: Keep answers under 3 paragraphs unless the user asks for detail.
You do not know: Pricing details, internal roadmaps, individual account data.
When asked about these, say: "I don't have access to that information, but our team at support@acme.com can help."Model preferences
Choose the primary model and optional fallback. Different models have different strengths:
| Model | Best for | Cost |
|---|---|---|
| gpt-4.1 | Complex reasoning, long documents | High |
| gpt-4.1-mini | Balanced — most agents start here | Medium |
| gpt-4.1-nano | High-volume, fast responses | Low |
| claude-sonnet-4 | Writing, nuanced conversation | Medium |
| gemini-2.5-flash | Multimodal, speed | Low |
Knowledge bases
- 1Go to Knowledge → New knowledge base and give it a name.
- 2Upload PDFs, Word docs, Markdown files, CSVs, or paste URLs. Akili chunks and embeds them automatically.
- 3In the agent settings, attach one or more knowledge bases.
- 4During chat, Akili searches the knowledge bases with cosine similarity (RAG) and injects relevant passages into the system prompt before sending to the model.
Note: Knowledge base search uses OpenAI text-embedding-3-small. Make sure OPENAI_API_KEY is configured if you want to use RAG.
Conversation starters
Provide 3–5 conversation starter prompts that appear when a user opens the agent. These help users understand what the agent can do.
- Keep starters short — one sentence each
- Cover different use cases (e.g. one about onboarding, one about billing, one about features)
- Starters are plain text — they pre-fill the user's message box when clicked
Agent capabilities
- Web search — enables real-time Bing search grounding (configure Bing Search API key in Admin → Providers → Other integrations)
- Image generation — generates durable images with the image-role model configured in Admin; available in authenticated chat and webchat
- Code execution — enables the agentic code sandbox for multi-step tool use
- Canvas — creates and updates private long-form artifacts in authenticated chat; anonymous webchat requires a channel-scoped artifact grant
- File attachments — allows users to upload files into the chat
Note: Platform administrators control Image Generation and Canvas under Platform Settings → AI Capabilities. Image Generation also requires an enabled model bound to the image role.
Agent versioning
- 1From the agent detail page, click "Save version" to snapshot the current configuration.
- 2Versions are immutable — each snapshot includes the system prompt, model preferences, and capability flags at that point in time.
- 3To roll back, click Versions, select the version you want, and click "Restore".
Deploying agents
Agents can be deployed beyond the Akili web app:
- Slack — add a bot token and signing secret; the agent responds to @mentions and DMs
- Microsoft Teams — configure a Bot Framework App ID and password; deploy to channels
- Webchat widget — embed a <script> tag on any website; ~14 KB, zero dependencies
- API — call POST /api/agents/:id/chat with a Bearer token to integrate programmatically