> ## Documentation Index > Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update an Agent > Update an existing agent's configuration or deploy a new version. ## OpenAPI ````yaml POST /agents/{agentName} openapi: 3.0.0 info: title: Pipecat Cloud version: 1.0.0 description: Private API for Pipecat Cloud agent management servers: - url: https://api.pipecat.daily.co/v1 description: API server security: - PrivateKeyAuth: [] paths: /agents/{agentName}: post: summary: Update an agent deployment operationId: updateService parameters: - name: agentName in: path required: true description: Name of the agent to update schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateServiceRequest' example: image: your-dockername/voice-starter:0.1 nodeType: arm imagePullSecretSet: dockerhub-credentials secretSet: voice-starter-secrets autoScaling: minAgents: 1 maxAgents: 10 krispViva: audioFilter: tel agentProfile: agent-1x maxSessionDuration: 3600 responses: '200': description: Agent deployment updated successfully content: application/json: schema: $ref: '#/components/schemas/ServiceDetailsResponse' example: name: voice-starter region: us-west ready: true available: true createdAt: '2025-04-19T01:20:27.564Z' updatedAt: '2025-04-19T01:25:47.229Z' desiredDeploymentId: 19db578d-808c-420a-a047-87edde4410c1 activeDeploymentId: 19db578d-808c-420a-a047-87edde4410c1 reconciledDeploymentId: 19db578d-808c-420a-a047-87edde4410c1 activeDeploymentReady: true autoScaling: maxReplicas: 10 minReplicas: 1 activeSessionCount: 0 agentProfile: agent-1x deployment: id: 19db578d-808c-420a-a047-87edde4410c1 manifest: apiVersion: pipecatcloud.daily.co/v1 kind: PCService metadata: name: voice-starter namespace: tiny-ferret-maroon-123 spec: dailyNodeType: arm image: your-dockername/voice-starter:0.1 autoScaling: minReplicas: 1 maxReplicas: 10 imagePullSecretName: dockerhub-credentials envFromSecretNames: - voice-starter-secrets resources: cpu: 500m memory: 1Gi krispModels: enabled: false krispViva: audioFilters: true maxSessionDurationSeconds: 3600 serviceId: b59a68ee-61c8-4d99-9ceb-e99a3953bdac createdAt: '2025-04-19T01:25:47.225Z' updatedAt: '2025-04-19T01:25:47.225Z' krispViva: audioFilter: tel currentRevision: deploymentID: 19db578d-808c-420a-a047-87edde4410c1 phase: Active readyReplicas: 1 phaseStartedAt: '2025-04-19T01:26:00.000Z' health: ready: true state: running restartCount: 0 replicasStarted: 1 previousRevision: null '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidParameters: summary: Invalid parameters value: error: Invalid parameters code: GENERIC_BAD_REQUEST secretRegionMismatch: summary: Secret set region mismatch value: error: >- Secret set 'my-secrets' is in region 'us-east' but service is in region 'us-west'. Secrets must be in the same region as the service. code: GENERIC_BAD_REQUEST imagePullSecretRegionMismatch: summary: Image pull secret region mismatch value: error: >- Image pull secret set 'dockerhub-creds' is in region 'us-east' but service is in region 'us-west'. Image pull secrets must be in the same region as the service. code: GENERIC_BAD_REQUEST imageAndBuildIdConflict: summary: Both image and buildId provided value: error: >- Cannot specify both image and buildId. Use one or the other. code: GENERIC_BAD_REQUEST buildNotFound: summary: Build not found value: error: Build not found code: GENERIC_BAD_REQUEST buildRegionMismatch: summary: Build region mismatch value: error: >- Build is in region 'eu-central' but service is in region 'us-west'. Builds must be in the same region as the service. code: GENERIC_BAD_REQUEST buildNotReady: summary: Build not successful value: error: >- Build is not ready (status: building). Only successful builds can be deployed. code: GENERIC_BAD_REQUEST '404': description: Agent or referenced secret not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Service not found code: NOT_FOUND '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Internal server error code: INTERNAL_SERVER_ERROR security: - PrivateKeyAuth: [] components: schemas: UpdateServiceRequest: type: object properties: image: type: string description: >- The container image to use for the agent. Cannot be specified together with `buildId`. example: your-username/my-agent:latest buildId: type: string format: uuid description: >- The ID of a successful cloud build to deploy. Cannot be specified together with `image`. The build must be in the same region as the agent. example: 123e4567-e89b-12d3-a456-426614174000 nodeType: type: string description: >- The type of node to run the agent on. Only `arm` is supported at this time. default: arm example: arm imagePullSecretSet: type: string description: The name of the image pull secret set to use example: dockerhub-credentials secretSet: type: string description: The name of the secret set to use example: my-agent-secrets autoScaling: type: object description: Auto-scaling configuration for the agent properties: minAgents: type: integer description: Minimum number of agents example: 1 maxAgents: type: integer description: 'Maximum number of agents (Default: 50)' example: 10 krispViva: type: object description: >- Krisp VIVA noise cancellation configuration. [Learn more](/pipecat-cloud/guides/krisp-viva). properties: audioFilter: type: string nullable: true description: >- 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. enum: - tel - pro - null example: tel agentProfile: type: string description: >- 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. enum: - agent-1x - agent-2x - agent-3x default: agent-1x example: agent-1x forceRedeploy: type: boolean description: >- Force a new deployment even if the configuration hasn't changed. Useful for picking up updated container images when using mutable tags like `latest`, or for refreshing modified secret values. default: false example: true maxSessionDuration: type: integer description: >- 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. minimum: 60 maximum: 14400 default: 7200 example: 3600 ServiceDetailsResponse: type: object properties: name: type: string description: Name of the agent region: type: string description: The region where the agent is deployed ready: type: boolean description: >- 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: type: boolean description: >- 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: type: string format: date-time description: Creation timestamp of the agent updatedAt: type: string format: date-time description: Last update timestamp desiredDeploymentId: type: string description: >- ID of the deployment that was requested. Use this to track which deployment should be running. activeDeploymentId: type: string description: >- **Deprecated**: Use `desiredDeploymentId` instead. ID of the requested deployment. deprecated: true reconciledDeploymentId: type: string description: >- 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: type: boolean description: >- **Deprecated**: Use `ready` instead. Whether the active deployment is ready. This field is redundant with `ready` and will be removed in a future version. deprecated: true autoScaling: type: object properties: maxReplicas: type: integer description: Maximum number of agent replicas minReplicas: type: integer description: Minimum number of agent replicas activeSessionCount: type: integer description: Number of active sessions deployment: type: object nullable: true description: Details of the current deployment properties: id: type: string description: Unique identifier for the deployment manifest: type: object description: Kubernetes manifest for the deployment properties: apiVersion: type: string description: API version of the manifest kind: type: string description: Kind of Kubernetes resource metadata: type: object description: Metadata for the resource properties: name: type: string description: Name of the agent namespace: type: string description: Kubernetes namespace spec: type: object description: Specification for the agent deployment properties: dailyNodeType: type: string description: Type of node to run on image: type: string description: >- Container image used. Redacted when deployed via a build. autoScaling: type: object description: Auto-scaling configuration properties: minReplicas: type: integer description: Minimum number of replicas maxReplicas: type: integer description: Maximum number of replicas imagePullSecretName: type: string description: Name of the image pull secret used envFromSecretNames: type: array description: Names of secrets to use as environment variables items: type: string resources: type: object description: Resource allocation for the agent properties: cpu: type: string description: CPU allocation memory: type: string description: Memory allocation krispViva: type: object description: Krisp VIVA configuration properties: audioFilters: type: boolean description: Whether Krisp VIVA audio filters are enabled maxSessionDurationSeconds: type: integer description: >- Maximum session duration in seconds configured for this service. Absent when the service is using the platform default. serviceId: type: string description: ID of the service this deployment belongs to createdAt: type: string format: date-time description: Creation timestamp of the deployment updatedAt: type: string format: date-time description: Last update timestamp of the deployment agentProfile: type: string description: The agent profile used for resource allocation nullable: true krispViva: type: object nullable: true description: Krisp VIVA status properties: audioFilter: type: string nullable: true description: >- The currently configured Krisp VIVA audio filter model (tel, pro, or null if disabled) currentRevision: description: Status of the current (latest) deployment revision nullable: true allOf: - $ref: '#/components/schemas/RevisionInfo' previousRevision: description: >- Status of the previous deployment revision (present during rolling updates) nullable: true allOf: - $ref: '#/components/schemas/RevisionInfo' ErrorResponse: type: object properties: error: type: string description: Error message code: type: string description: Error code RevisionInfo: type: object properties: deploymentID: type: string description: ID of the deployment for this revision phase: type: string enum: - Creating - Validating - Active - Draining - Failed description: Current phase of the revision readyReplicas: type: integer description: Number of ready replicas for this revision phaseStartedAt: type: string format: date-time description: Timestamp when the current phase started health: $ref: '#/components/schemas/RevisionHealth' hasInfrastructureIssue: type: boolean description: >- Set to true when an internal infrastructure component is experiencing issues. If absent, infrastructure is healthy. Contact support if this flag appears. RevisionHealth: type: object description: >- Health summary for the agent's code. Present once replicas have started running. properties: ready: type: boolean description: Whether the agent code is passing readiness checks state: type: string enum: - running - waiting - terminated description: Current state of the agent code restartCount: type: integer description: Total number of restarts across all replicas replicasStarted: type: integer description: Number of replicas that have been started (may or may not be ready) reason: type: string description: >- Reason for the current state (e.g., CrashLoopBackOff, ImagePullBackOff, OOMKilled, Error) lastExitCode: type: integer description: >- Exit code from the most recent crash (e.g., 1 for application error, 137 for out-of-memory) lastTerminationReason: type: string description: >- Why the agent code last exited. When reason is CrashLoopBackOff, this reveals the underlying cause (e.g., OOMKilled, Error) message: type: string description: >- Detailed error output from the crash, such as a Python traceback. Captured from the agent's stderr/stdout on non-zero exit. securitySchemes: PrivateKeyAuth: type: http scheme: bearer description: >- Authentication requires a Pipecat Cloud Private API token. Generate a Private API key from your Dashboard (Settings > API Keys > Private > Create key) and include it as a Bearer token in the Authorization header. ````