Agent Definition
An agent definition is a configuration that specifies how your AI agent behaves during voice or chat conversations
About
An agent definition is the configuration record for a single AI agent in Simulate. It describes which agent is being tested and how the platform connects to it.
Each agent definition includes:
- A name and type (voice or chat)
- Connection details: provider (e.g. Vapi, Retell), assistant ID, and API key
- For voice agents: contact number, inbound/outbound setting, and language(s)
- For custom/WebSocket agents: websocket URL and headers
- Optional knowledge base and observability provider
Agent definitions support versioning. Each version stores a snapshot of the configuration so you can run simulations against a specific version, compare versions, or roll back. Scenarios and run tests reference an agent definition (and a chosen version) to execute tests against that agent.
Creating Agent Definition
Navigate to Agent Definition
Open Simulate from the sidebar and click Agent Definition.
Provide basic information
Fill in the required basic information.
| Field | Description |
|---|---|
| Agent Type | Choose Voice or Chat. Voice agents are used for phone or voice-channel simulations; chat agents for chat-based ones. |
| Agent Name | A unique, descriptive name for your agent. This name appears when you select an agent in scenarios and run tests, and is used for the observability project name if you enable observability. |
| Language | The primary language (or multiple languages) the agent will use. Select one or more from the supported list (e.g. English, Spanish, French). This drives language-specific behavior in simulations. |
If you already have an assistant configured in a provider (e.g. Vapi or Retell), you can use Sync from provider (see the next steps) to pull the assistant’s name and prompt into the form after entering the provider, API key, and assistant ID.
Agent configuration
Configure how the platform connects to your agent. This section is required for outbound agents and for syncing or running tests.
| Field | Description |
|---|---|
| Voice/Chat Provider | The provider that hosts your agent (e.g. Vapi, Retell, Eleven Labs, or Others for custom/WebSocket). See supported providers for setup. |
| Assistant ID | The assistant or agent ID from your provider’s dashboard. Required when connection type is Outbound. |
| API Key | Your provider API key for authentication. Required when connection type is Outbound. |
| Observability Provider | Enable observability to track calls and performance. When enabled, a project is created in Observe under your agent’s name. |
For Outbound agents, both Assistant ID and API Key must be set; otherwise saving will fail with a validation error.
Sync from provider (optional)
If your agent is already set up in Vapi or Retell, you can pull the assistant’s name and system prompt into the form. Enter the Voice/Chat Provider, Assistant ID, and API Key, then use the sync action. The platform retrieves the assistant name and prompt and fills the corresponding fields. If the API key or assistant ID is wrong, you will see an error.
Define agent behavior
Describe what the agent does and optionally attach a knowledge base.
- Description / model: Add a description of the agent’s purpose and, if needed, set the model and model details (e.g. system prompt, personality). This is snapshotted when you create a version. If you used “Sync from provider,” the prompt may already be filled.
- Knowledge base (optional): A knowledge base is the source of truth your agent is expected to know (FAQs, SOPs, product docs, compliance policies). Attaching one lets evals check whether the agent’s responses match your real content, catching wrong answers or off-policy responses.
Tip
Learn more in the Knowledge base overview.
Set contact information
Configure contact and call direction (for voice agents).
- Contact number: The phone number the agent will use.
- Country code: Select the country code for the contact number.
- Connection type:
- Inbound (ON): The agent receives incoming calls from customers.
- Outbound (OFF): The agent places calls to customers. For Outbound, Assistant ID and API Key (in Agent configuration) must be set.
Add version details
When saving, provide a commit message to track changes. The system creates a new version with a snapshot of the current configuration.
Enable observability (optional)
Turn this on to track your agent’s performance. After you enable it and run a test, a project is created in your agent’s name in the Observe section.
Agent Detail View
After creating an agent, open it from the list to access the detail screen. Here you can edit the configuration, manage versions, and view results.
- Agent select dropdown: Switch between agents without leaving the page.
- Version management (left): All versions for this agent, newest first. Click a version to load it.
- Create new version: Opens a drawer to create a new version from the current config.
View and edit the agent’s definition. Shows the same fields used during creation.
- Basic information: Agent name, type, and language(s).
- Provider and connection: Voice/Chat provider, Assistant ID, API key, observability provider.
- Behavior: Description, model, model details, and optional knowledge base.
- Contact (voice agents): Contact number, country code, and connection type.
Saving creates a new version with a snapshot of the updated config. Previous versions remain in the version list. You can also delete the agent from this tab.
Each version is a saved snapshot of your agent’s configuration. A version has a version number, status (Draft, Active, Archived, Deprecated), and a commit message. Only one version can be Active at a time; run tests use the active version by default.
Create a new version
Click Create new version. Enter a Commit message, update fields if needed, then click Save.
Tip
Switch to a different version
Click a version in the list on the left. The main area loads that version’s config. Saving from here creates a new version.
Note
Activate a version
Use Activate on a version to make it the default for run tests. The previously active version remains in the list.
Restore from a version
Use Restore to revert the agent definition to an older snapshot. You can then save as a new version.
Delete a version
Use Delete to soft-delete a version. You cannot delete the only active version; activate another version first.
After running simulations, you can view performance analytics and call logs for each agent version. See View Results for details.