Create Agent

Creates a new AI voice agent with customizable settings.

Endpoint

POST /v1/agents

Authentication

Requires a valid API key or user authentication token.

Request Body

{
  "name": "string",
  "description": "string",
  "system_prompt": "string",
  "language": "string",
  "voice_id": "string",
  "tts_provider": "string",
  "stt_provider": "string",
  "llm_model": "string",
  "knowledge_base_ids": ["string"]
}

Request Fields

Field	Type	Required	Description
name	string	Yes	Display name of the agent
description	string	No	Description of the agent's purpose
system_prompt	string	No	Instructions that define the agent's personality and behavior
language	string	No	Language code (e.g., "en" for English). Default: "en"
voice_id	string	No	Identifier for the agent's voice
tts_provider	string	No	Text-to-speech provider. Default: "krosaimlingual"
stt_provider	string	No	Speech-to-text provider. Default: "krosaimlingual"
llm_model	string	No	Large language model to use. Default: "krosaimlingual"
knowledge_base_ids	array	No	List of knowledge base IDs the agent can access

Response

Returns the created agent object with its configuration and metadata.

Response Format

{
  "id": "string",
  "name": "string",
  "description": "string",
  "system_prompt": "string",
  "language": "string",
  "voice_id": "string",
  "tts_provider": "string",
  "stt_provider": "string",
  "llm_model": "string",
  "knowledge_base_ids": ["string"],
  "created_at": "datetime",
  "updated_at": "datetime",
  "created_by": "string"
}

Example Request

curl -X POST "https://api.krosai.com/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Expert",
    "description": "Helps users with product information and recommendations",
    "system_prompt": "You are a knowledgeable product expert for KrosAI. You help users understand our products and make recommendations based on their needs. Be friendly, concise, and helpful.",
    "language": "en",
    "voice_id": "pidgin",
    "tts_provider": "krosaimlingual",
    "stt_provider": "krosaimlingual",
    "llm_model": "krosaimlingual",
    "knowledge_base_ids": ["kb-product-catalog"]
  }'

Example Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Product Expert",
  "description": "Helps users with product information and recommendations",
  "system_prompt": "You are a knowledgeable product expert for KrosAI. You help users understand our products and make recommendations based on their needs. Be friendly, concise, and helpful.",
  "language": "en",
  "voice_id": "nova",
  "tts_provider": "krosaimlingual",
  "stt_provider": "krosaimlingual",
  "llm_model": "krosaimlingual",
  "knowledge_base_ids": ["kb-product-catalog"],
  "created_at": "2023-07-10T15:30:00Z",
  "updated_at": "2023-07-10T15:30:00Z",
  "created_by": "user-12345"
}

Error Responses

Status Code	Description
400	Bad Request - Invalid input data
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
500	Internal Server Error

Notes

• The system prompt defines the agent's personality, behavior, and capabilities. A well-crafted system prompt is essential for creating an effective agent.

• Available voice options depend on the selected TTS provider.

• Knowledge bases must exist before they can be associated with an agent.