Sign in

v1

latestOpenAPI 3.0.02026-07-26242779.3 KB

Create a new agent

post/agents

Request body

serviceNamestring required

Name of the agent to create.

Must start with a lowercase letter or number, can include hyphens, and must end with a lowercase letter or number. No uppercase letters or special characters allowed. Maximum 54 characters.

imagestring

The container image to use for the agent. Either image or buildId must be provided, but not both.

buildIdstring uuid

The ID of a successful cloud build to deploy. Either image or buildId must be provided, but not both. The build must be in the same region as the agent.

regionstring

The region where the agent will be deployed. If not specified, defaults to us-west. All secrets and image pull secrets referenced by this agent must be in the same region.

nodeTypestring

The type of node to run the agent on. Only arm is supported at this time.

imagePullSecretSetstring

The name of the image pull secret set to use

secretSetstring

The name of the secret set to use

agentProfile'agent-1x' | 'agent-2x' | 'agent-3x'

The agent profile to use for resource allocation. Valid values are:

  • agent-1x: 0.5 vCPU and 1 GB of memory. Best for voice agents.
  • agent-2x: 1 vCPU and 2 GB of memory. Well suited for voice and video agents or voice agents requiring extra processing.
  • agent-3x: 1.5 vCPU and 3 GB of memory. Best for voice and video agents requiring extra processing or multiple video inputs.
maxSessionDurationinteger

Maximum session duration in seconds. When a session reaches this limit, the agent's connection is forcibly closed — the session is cut off mid-flight with no notice to the bot. Valid range: 60 to 14400 (4 hours). Defaults to 7200 (2 hours) when unset.

Example request

{
  "serviceName": "my-voice-agent",
  "image": "your-username/my-agent:latest",
  "buildId": "123e4567-e89b-12d3-a456-426614174000",
  "region": "us-west",
  "nodeType": "arm",
  "imagePullSecretSet": "dockerhub-credentials",
  "secretSet": "my-agent-secrets",
  "autoScaling": {
    "minAgents": 1,
    "maxAgents": 20
  },
  "krispViva": {
    "audioFilter": "tel"
  },
  "agentProfile": "agent-1x",
  "maxSessionDuration": 3600
}

Response

Agent created successfully

namestring

Name of the agent

regionstring

The region where the agent is deployed

readyboolean

Whether the latest deployment has passed validation and is ready. For scale-to-zero agents, this is true even when scaled down to zero replicas.

availableboolean

Whether the agent can accept new sessions. True when any pods are ready to handle traffic, or when scaled to zero but healthy (requests will queue and trigger scale-up). During rolling updates, this may be true even if ready is false, as old pods continue serving while new ones validate.

createdAtstring date-time

Creation timestamp of the agent

updatedAtstring date-time

Last update timestamp

desiredDeploymentIdstring

ID of the deployment that was requested. Use this to track which deployment should be running.

activeDeploymentIdstring

Deprecated: Use desiredDeploymentId instead. ID of the requested deployment.

reconciledDeploymentIdstring

ID of the deployment that the operator has actually reconciled. Compare with desiredDeploymentId to determine if a deployment update has been processed. When these match and ready is true, the deployment is fully complete.

activeDeploymentReadyboolean

Deprecated: Use ready instead. Whether the active deployment is ready. This field is redundant with ready and will be removed in a future version.

activeSessionCountinteger

Number of active sessions

agentProfilestring nullable

The agent profile used for resource allocation