---
title: "Create a new agent"
method: POST
path: "/agents"
---

# Create a new agent

`POST /agents`

## Request body

- CreateServiceRequest
  - `serviceName` string, 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.
  - `image` string — The container image to use for the agent. Either `image` or `buildId` must be provided, but not both.
  - `buildId` string, 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.
  - `region` string — 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.
  - `nodeType` string — The type of node to run the agent on. Only `arm` is supported at this time.
  - `imagePullSecretSet` string — The name of the image pull secret set to use
  - `secretSet` string — The name of the secret set to use
  - `autoScaling` object — Auto-scaling configuration for the agent
    - `minAgents` integer — Minimum number of agents
    - `maxAgents` integer — Maximum number of agents (Default: 50)
  - `krispViva` object — Krisp VIVA noise cancellation configuration. [Learn more](/pipecat-cloud/guides/krisp-viva).
    - `audioFilter` 'tel' | 'pro' | 'null', nullable — The Krisp VIVA audio filter model to use: - `tel`: Optimized for telephony, cellular, landline, mobile, desktop, and browser (up to 16kHz) - `pro`: Optimized for mobile, desktop, and browser with WebRTC (up to 32kHz) - `null`: Disables Krisp VIVA By default, Pipecat processes input audio at 16kHz, making `tel` appropriate for most use cases.
  - `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.
  - `maxSessionDuration` integer — 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.

## Response `200`

Agent created successfully

- ServiceDetailsResponse
  - `name` string — Name of the agent
  - `region` string — The region where the agent is deployed
  - `ready` boolean — 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.
  - `available` boolean — 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.
  - `createdAt` string, date-time — Creation timestamp of the agent
  - `updatedAt` string, date-time — Last update timestamp
  - `desiredDeploymentId` string — ID of the deployment that was requested. Use this to track which deployment should be running.
  - `activeDeploymentId` string — **Deprecated**: Use `desiredDeploymentId` instead. ID of the requested deployment.
  - `reconciledDeploymentId` string — 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.
  - `activeDeploymentReady` boolean — **Deprecated**: Use `ready` instead. Whether the active deployment is ready. This field is redundant with `ready` and will be removed in a future version.
  - `autoScaling` object
    - `maxReplicas` integer — Maximum number of agent replicas
    - `minReplicas` integer — Minimum number of agent replicas
  - `activeSessionCount` integer — Number of active sessions
  - `deployment` object, nullable — Details of the current deployment
    - `id` string — Unique identifier for the deployment
    - `manifest` object — Kubernetes manifest for the deployment
      - `apiVersion` string — API version of the manifest
      - `kind` string — Kind of Kubernetes resource
      - `metadata` object — Metadata for the resource
        - `name` string — Name of the agent
        - `namespace` string — Kubernetes namespace
      - `spec` object — Specification for the agent deployment
        - `dailyNodeType` string — Type of node to run on
        - `image` string — Container image used. Redacted when deployed via a build.
        - `autoScaling` object — Auto-scaling configuration
          - `minReplicas` integer — Minimum number of replicas
          - `maxReplicas` integer — Maximum number of replicas
        - `imagePullSecretName` string — Name of the image pull secret used
        - `envFromSecretNames` string[] — Names of secrets to use as environment variables
        - `resources` object — Resource allocation for the agent
          - `cpu` string — CPU allocation
          - `memory` string — Memory allocation
        - `krispViva` object — Krisp VIVA configuration
          - `audioFilters` boolean — Whether Krisp VIVA audio filters are enabled
        - `maxSessionDurationSeconds` integer — Maximum session duration in seconds configured for this service. Absent when the service is using the platform default.
    - `serviceId` string — ID of the service this deployment belongs to
    - `createdAt` string, date-time — Creation timestamp of the deployment
    - `updatedAt` string, date-time — Last update timestamp of the deployment
  - `agentProfile` string, nullable — The agent profile used for resource allocation
  - `krispViva` object, nullable — Krisp VIVA status
    - `audioFilter` string, nullable — The currently configured Krisp VIVA audio filter model (tel, pro, or null if disabled)
  - `currentRevision` RevisionInfo
    - `deploymentID` string — ID of the deployment for this revision
    - `phase` 'Creating' | 'Validating' | 'Active' | 'Draining' | 'Failed' — Current phase of the revision
    - `readyReplicas` integer — Number of ready replicas for this revision
    - `phaseStartedAt` string, date-time — Timestamp when the current phase started
    - `health` RevisionHealth — Health summary for the agent's code. Present once replicas have started running.
      - `ready` boolean — Whether the agent code is passing readiness checks
      - `state` 'running' | 'waiting' | 'terminated' — Current state of the agent code
      - `restartCount` integer — Total number of restarts across all replicas
      - `replicasStarted` integer — Number of replicas that have been started (may or may not be ready)
      - `reason` string — Reason for the current state (e.g., CrashLoopBackOff, ImagePullBackOff, OOMKilled, Error)
      - `lastExitCode` integer — Exit code from the most recent crash (e.g., 1 for application error, 137 for out-of-memory)
      - `lastTerminationReason` string — Why the agent code last exited. When reason is CrashLoopBackOff, this reveals the underlying cause (e.g., OOMKilled, Error)
      - `message` string — Detailed error output from the crash, such as a Python traceback. Captured from the agent's stderr/stdout on non-zero exit.
    - `hasInfrastructureIssue` boolean — Set to true when an internal infrastructure component is experiencing issues. If absent, infrastructure is healthy. Contact support if this flag appears.
  - `previousRevision` RevisionInfo
    - `deploymentID` string — ID of the deployment for this revision
    - `phase` 'Creating' | 'Validating' | 'Active' | 'Draining' | 'Failed' — Current phase of the revision
    - `readyReplicas` integer — Number of ready replicas for this revision
    - `phaseStartedAt` string, date-time — Timestamp when the current phase started
    - `health` RevisionHealth — Health summary for the agent's code. Present once replicas have started running.
      - `ready` boolean — Whether the agent code is passing readiness checks
      - `state` 'running' | 'waiting' | 'terminated' — Current state of the agent code
      - `restartCount` integer — Total number of restarts across all replicas
      - `replicasStarted` integer — Number of replicas that have been started (may or may not be ready)
      - `reason` string — Reason for the current state (e.g., CrashLoopBackOff, ImagePullBackOff, OOMKilled, Error)
      - `lastExitCode` integer — Exit code from the most recent crash (e.g., 1 for application error, 137 for out-of-memory)
      - `lastTerminationReason` string — Why the agent code last exited. When reason is CrashLoopBackOff, this reveals the underlying cause (e.g., OOMKilled, Error)
      - `message` string — Detailed error output from the crash, such as a Python traceback. Captured from the agent's stderr/stdout on non-zero exit.
    - `hasInfrastructureIssue` boolean — Set to true when an internal infrastructure component is experiencing issues. If absent, infrastructure is healthy. Contact support if this flag appears.

## Other responses

- `400` — Invalid request or agent already exists
- `404` — Secret set or image pull secret set not found
- `500` — Internal server error

---

[API](https://skmtc.dev/pipecat/apis/pipecat-cloud.md) · [All operations](https://skmtc.dev/pipecat/apis/pipecat-cloud/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pipecat/pipecat-cloud/revisions/acd0f7dfe734/schema)