Create Agent Definition — API

Create a new agent definition and its initial version. Accepts agent type, name, provider, API key, and system prompt. Returns the created agent object.

POST https://api.futureagi.com/simulate/agent-definitions/create/

Authentication

X-Api-Key API Key Required

Your Future AGI API key used to authenticate requests. You can find and manage your API keys in the Dashboard under Settings.

X-Secret-Key Secret Key Required

Your Future AGI secret key, used alongside the API key for request authentication. This is generated when you create an API key in the Dashboard.

Request body

agent_type string Required

Values: voice, text.

agent_name string Required

Display name for the agent.

commit_message string Required

Commit message describing the initial version. Defaults to an auto-generated message if omitted.

provider string Optional

External voice provider. Values: vapi, retell, eleven_labs, livekit, livekit_bridge, others. Required for voice agents.

api_key string Optional

API key for the external voice provider. Required for outbound agents or when observability_enabled is true.

assistant_id string Optional

Assistant identifier from the external provider. Required for outbound agents or when observability_enabled is true.

authentication_method string Optional

Provider authentication method. Values: api_key. Required for non-others voice agents that are outbound or have observability_enabled set.

description string Optional

Description for the initial agent version.

language string Optional

Primary language as an ISO 639-1 code (e.g. en, es).

languages array of string Optional

List of supported ISO 639-1 language codes.

knowledge_base UUID Optional

UUID of a knowledge base to link to the agent.

contact_number string Optional

Full phone number with country code prefix (e.g. +14155551234). Number portion must be 10–12 digits. Not required for livekit / livekit_bridge providers, or when api_key and assistant_id are both provided (web bridge).

inbound boolean Optional

Whether the agent handles inbound calls. Defaults to false (outbound-only).

observability_enabled boolean Optional

Enables observability with the external provider. Requires api_key and assistant_id.

model string Optional

AI model identifier (e.g. gpt-4o, claude-3-sonnet).

model_details object Optional

Provider-specific model settings (temperature, max tokens, etc.).

websocket_url string Optional

WebSocket URL for real-time providers. Must start with ws:// or wss://.

websocket_headers object Optional

Custom headers for the WebSocket connection.

replay_session_id UUID Optional

UUID of a replay session to initialize the agent from.

livekit_url string Optional

LiveKit server URL (e.g. wss://your-server.livekit.cloud). Required for livekit and livekit_bridge providers.

livekit_api_key string Optional

LiveKit API key.

livekit_api_secret string Optional

LiveKit API secret. Write-only; not returned in responses.

livekit_agent_name string Optional

Agent name registered on the LiveKit server.

livekit_config_json object Optional

LiveKit room configuration metadata.

livekit_max_concurrency integer Optional

Max concurrent LiveKit sessions. Min 1, capped by org limit. Defaults to 5.

Response

201 Created
message string
Confirmation message.
agent object

The newly created agent definition.

id string
UUID of the agent definition.
agent_name string
Display name.
agent_type string
voice or text.
contact_number string
Phone number with country code, or null for text agents.
inbound boolean
Whether the agent handles inbound calls.
description string
Agent description.
assistant_id string
External assistant ID, or null.
provider string
Voice provider, or null for text agents.
language string
Primary language ISO 639-1 code.
languages array
All supported language codes.
authentication_method string
Provider auth method.
websocket_url string
WebSocket URL, or null.
websocket_headers object
WebSocket headers, or null.
workspace string
Workspace UUID, or null.
knowledge_base string
Linked knowledge base UUID, or null.
organization string
Organization UUID.
api_key string
Provider API key (masked).
observability_provider string
Observability provider, or null.
created_at datetime
ISO 8601 creation timestamp.
updated_at datetime
ISO 8601 last-modified timestamp.
model string
AI model identifier, if set.
model_details object
Extended model configuration.
livekit_url string
LiveKit server URL, or null.
livekit_api_key string
LiveKit API key, or null.
livekit_agent_name string
LiveKit agent name, or null.
livekit_config_json object
LiveKit room configuration.
livekit_max_concurrency integer
Max concurrent LiveKit sessions. Defaults to 5.

Errors

400 Bad Request Optional

Missing required fields, invalid provider configuration, or livekit_max_concurrency exceeds org limit.

401 Unauthorized Optional

Invalid or missing API credentials.

404 Not Found Optional

Replay session not found.

500 Internal Server Error Optional

Unexpected server error.

GET /
Authentication
REQUEST 
 
 
  
 
 RESPONSE