Create your first agent
An agent is a system prompt, a model and a set of channels, plus whatever knowledge, tools and skills you attach to it. This page walks through the agent form field by field.
Before you start
Section titled “Before you start”Add the API key for the model provider you plan to use in Workspace settings. Without it the agent saves, but fails the first time someone talks to it.
Create the agent
Section titled “Create the agent”- Open Agents and select New agent.
- Fill in Identity and System Prompt.
- Choose the Channels the agent answers on.
- Configure the model under AI Model Configuration.
- Select Create Agent.
If the only channel you turned on is Web Chatbot, the agent opens in the visual canvas after it is created, so you can attach knowledge and tools straight away. Otherwise you return to the agent list.
Workspace admins also see Create with AI, which opens the Agent Builder: an agent that designs and creates agents for you through conversation.
Identity
Section titled “Identity”| Field | What it does |
|---|---|
| Agent ID | Required. A stable identifier used in the agent’s integration URLs. Letters, numbers, underscores and hyphens, up to 100 characters. It cannot be changed after the agent is created. |
| Agent Name | Required. The name people see in the agent list, the web chat selector and the canvas. |
| Description | What the agent is for. Shown in the agent list. |
| Avatar | After the first save you can set an avatar image URL. It appears with the agent’s replies in web chat. |
System Prompt
Section titled “System Prompt”The instructions the agent follows on every turn: its role, its audience, its tone, what it must never do, and when to hand off to a person. It is required. The counter under the field shows its length in characters.
Write it the way you would brief a new team member: the goal, the audience, the rules, and what to do when unsure.
Channels
Section titled “Channels”Select a card to switch a channel on or off. Web Chatbot, CLI and Google Chat start switched on for a new agent; turn off the ones you don’t need. Step-by-step setup for each channel is in the channels overview.
| Channel | What it means |
|---|---|
| Web Chatbot | The agent appears in the workspace web chat selector. When off, it is hidden from the selector. |
| CLI | The agent can be used from the VirtuAI command-line client. |
| The agent answers WhatsApp messages sent to the webhook shown in its integration URLs. | |
| Voice | Phone calls through Twilio. |
| Web Voice Widget | An embeddable voice widget for your website. Requires Voice to be on. |
| Telegram | A Telegram bot. Opens a Telegram Configuration card. |
| Slack | A Slack bot. Opens a Slack Configuration card. |
| Google Chat | The agent responds in Google Chat spaces. |
Telegram Configuration
Section titled “Telegram Configuration”Full setup: Telegram.
| Field | What it does |
|---|---|
| Bot Token | Required. The token you get from @BotFather. |
| Bot Username | The bot’s username without @. Needed to generate invite links. |
| Waiting Message | Shown while the agent works on a request. |
After the first save, the card also shows:
- Webhook Registration: Register Webhook points your bot at this agent and generates a new secret that Telegram sends with every message; Unregister frees the bot so another agent can use it. Telegram requires a public HTTPS URL.
- Invite Link: + Generate creates a link that authorizes one Telegram user to talk to the bot. Links expire after 24 hours and are single-use.
- Authorized Users: the Telegram users who joined through an invite. Revoke removes a user’s access.
Slack Configuration
Section titled “Slack Configuration”Full setup: Slack.
| Field | What it does |
|---|---|
| Bot Token | Required. The Bot User OAuth Token (xoxb-…) from your Slack app’s OAuth & Permissions page. |
| Signing Secret | Required. From your Slack app’s Basic Information page. |
| Waiting Message | Shown while the agent works on a request. |
Bot tokens and signing secrets are encrypted when you save them and are never shown again. On Telegram and Slack, a saved one is marked Configured and its field reads “Stored — leave blank to keep it”. Leave it blank to keep it, or type a new value to replace it.
After the first save, the card shows the two URLs to paste into your Slack app at api.slack.com/apps: Event Subscriptions → Request URL and Slash Commands → Request URL.
AI Model Configuration
Section titled “AI Model Configuration”This card appears whenever a text channel is on, which is every agent except a voice-only one.
| Field | What it does |
|---|---|
| Provider | Google Gemini, Google Gemini (Vertex AI), OpenAI, Anthropic, Anthropic (Vertex AI), Local (Ollama) or OpenCode Go. |
| Model | The model the agent uses by default. The list shows the models available for the selected provider. |
| Temperature | 0.0 to 2.0. Default 0.7. Lower values give more consistent answers; higher values more varied ones. |
| Max Output Tokens | The longest reply the model may write in one turn. Default 1000. The upper limit depends on the model and is shown under the field. |
| Prompt Caching | Reuses the system prompt and tool definitions between turns to cut token cost and latency. Available for Anthropic, OpenAI and OpenCode Go. OpenAI caches automatically, so for OpenAI the switch only records your intent. Not available as a switch for Gemini. |
| Thinking level | Shown only for models that support it. Fast, Balanced (default) or Deep. Deeper thinking costs more output tokens and takes longer. The level is mapped onto the tiers of whichever model you choose, so it keeps working if you switch models. |
Below the fields is the list of models allowed in web chat: the models an employee can pick in the workspace web chat when talking to this agent. Each agent has its own list. You must select at least one model before you can save an agent with a text channel on.
Local (Ollama) agents
Section titled “Local (Ollama) agents”With Local (Ollama), the model runs on the user’s own machine through the VirtuAI CLI. These agents are used from the CLI, not from the web chat model picker.
- Model becomes a free-text Ollama tag, for example
qwen2.5-coder:7b. The model must already be pulled on the user’s machine. Prefer models that support tool calling. - Fallback provider (cloud) and Fallback model are required. When the CLI or Ollama is unavailable, the agent answers with the fallback model and shows a notice.
- Max Output Tokens sets Ollama’s per-turn generation limit. There is no preset maximum; about 4096 is a safe start.
Voice Configuration
Section titled “Voice Configuration”Shown when Voice is on.
| Field | What it does |
|---|---|
| Voice Provider | Gemini or ElevenLabs. |
| Language | Gemini only. The language the agent speaks, for example English (US), Spanish (Mexico) or Portuguese (Brazil). |
| Gemini Voice | Gemini only. One of the prebuilt Gemini voices, such as Aoede, Puck or Kore. |
| ElevenLabs Voice ID | Required with ElevenLabs. Find your voice IDs in your ElevenLabs dashboard. |
Deep Agent Mode
Section titled “Deep Agent Mode”The Harness field chooses how the agent works:
- Classic: a standard conversational agent.
- Deep: adds planning, skills, long-term memory and sub-agents.
See Deep agents for what changes and where deep mode applies.
Integration URLs
Section titled “Integration URLs”After you save, open the agent again and expand Integration URLs. Each entry has a copy button and belongs to this agent only, so different agents can serve different channels, numbers or bots.
| Entry | Use it for |
|---|---|
| Web Chat UI | The workspace web chat page. |
| Web Chat API, Web Chat API (Stream) | Calling the agent from your own application, as a single response or as a stream. |
| Web Voice Widget, Voice WebSocket | The web voice widget and its voice connection. |
| WhatsApp Webhook | The URL to configure in Twilio for WhatsApp. |
| Google Chat Webhook | The URL to configure in your Google Chat app. |
| Slack Events URL, Slack Slash Commands URL | The URLs to configure in your Slack app. |
| A2A Agent Card, A2A Endpoint (JSON-RPC) | Connecting the agent to another agent platform over the Agent2Agent (A2A) protocol. |
When integration key enforcement is on, the Voice WebSocket is marked Requires X-API-Key. It is the only entry that needs the key. WhatsApp and Google Chat are verified by their platform instead (a Twilio signature, or a Google token checked against your project number).
When Web Voice Widget is on, the section also shows the Web Voice Widget Embed Code, the HTML snippet to paste into your website. See Web voice widget.
Change an existing agent
Section titled “Change an existing agent”Open the agent, make your changes and select Update Agent. The Agent ID is fixed; everything else can change.
By default a saved change reaches every channel immediately. Turn on versioning at the top of the form to work in a draft and publish when you are ready. See Drafts and publishing.
Next steps
Section titled “Next steps”- Attach knowledge, tools and sub-agents in the visual canvas.
- Give the agent company knowledge with Knowledge bases.
- Let it take actions with Tools.
- Measure it with Evaluations.
- Test it with the go-live checklist.