> ## Documentation Index > Fetch the complete documentation index at: https://docs.coval.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update agent > Update specific fields of an existing agent configuration. ## OpenAPI ````yaml /api-reference/v1/agents-v1.yaml patch /agents/{agent_id} openapi: 3.0.3 info: title: Coval Agents API version: 1.0.0 description: | Manage configurations for simulations and evaluations. contact: name: Coval API Support email: support@coval.dev url: https://docs.coval.ai license: name: Proprietary url: https://coval.dev/terms servers: - url: https://api.coval.dev/v1 description: Production API security: - ApiKeyAuth: [] tags: - name: Agents description: CRUD operations for AI agent configurations paths: /agents/{agent_id}: patch: tags: - Agents summary: Update agent description: Update specific fields of an existing agent configuration. operationId: updateAgent parameters: - name: agent_id in: path required: true schema: type: string pattern: ^[A-Za-z0-9]{22}$ description: Agent resource ID example: abc123def456ghi789jklm requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAgentRequest' examples: partialUpdate: $ref: '#/components/examples/UpdateAgentPartial' clearFields: $ref: '#/components/examples/UpdateAgentClearFields' responses: '200': description: Agent updated successfully content: application/json: schema: $ref: '#/components/schemas/UpdateAgentResponse' examples: updated: $ref: '#/components/examples/AgentUpdated' '400': description: Invalid request body or validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '404': description: Agent not found, inactive, or belongs to different organization content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: $ref: '#/components/examples/AgentNotFoundError' '500': $ref: '#/components/responses/InternalError' security: - ApiKeyAuth: [] components: schemas: UpdateAgentRequest: type: object description: >- Partial update request (PATCH semantics - only provided fields are updated) properties: display_name: type: string description: Human-readable agent name minLength: 1 maxLength: 200 example: Updated Agent Name model_type: $ref: '#/components/schemas/SimulatorType' phone_number: type: string nullable: true description: Phone number in E.164 format or SIP address for voice/SMS agents maxLength: 200 example: '+9876543210' endpoint: type: string nullable: true description: Custom API endpoint URL maxLength: 200 example: https://api.newexample.com/agent prompt: type: string nullable: true description: Agent instructions/system prompt example: Updated instructions... customer_agent_id: type: string nullable: true minLength: 1 maxLength: 200 description: New external id for the agent example: my-support-agent language: type: string nullable: true maxLength: 200 description: Primary language for the agent example: en attributes: type: object nullable: true description: Free-form agent attributes. None means don't update; {} clears them. additionalProperties: true example: company_name: Acme Corp metadata: type: object nullable: true description: Simulator-specific configuration (null = no change, {} = clear) additionalProperties: true example: key: value workflows: type: object nullable: true description: Workflow configuration (null = no change, {} = clear) additionalProperties: true example: workflow: config metric_ids: type: array nullable: true description: Associated metric IDs (null = no change, [] = clear) items: type: string example: - abc123def456ghi789jklm test_set_ids: type: array nullable: true description: Associated test set IDs (null = no change, [] = clear) items: type: string example: - gT5wq2Hn tags: type: array nullable: true description: >- Tags to associate with this agent. Null or omitted leaves tags unchanged. Pass [] to clear all tags. items: type: string example: - production UpdateAgentResponse: type: object required: - agent properties: agent: $ref: '#/components/schemas/AgentResource' ErrorResponse: type: object description: Standard error response required: - error properties: error: type: object required: - code - message - details properties: code: type: string description: Error code enum enum: - INVALID_ARGUMENT - UNAUTHENTICATED - NOT_FOUND - ALREADY_EXISTS - INTERNAL example: INVALID_ARGUMENT message: type: string description: Human-readable error message example: Invalid request parameter details: type: array description: Detailed error information items: type: object properties: field: type: string nullable: true description: Field name that caused the error example: page_size description: type: string description: Detailed error description example: page_size must be between 1 and 100 SimulatorType: type: string description: > Agent type. Active types that can be created via the v1 API: - **MODEL_TYPE_VOICE**: Inbound voice calls (requires phone_number in E.164 format or SIP address) - **MODEL_TYPE_OUTBOUND_VOICE**: Outbound voice calls (requires endpoint webhook URL) - **MODEL_TYPE_CHAT**: Text-based chat agents (requires metadata.chat_endpoint) - **MODEL_TYPE_CHAT_A2A**: A2A JSON-RPC chat agents (requires metadata.chat_endpoint) - **MODEL_TYPE_CHAT_WEBSOCKET**: Text chat over WebSocket (requires metadata.endpoint in direct mode) - **MODEL_TYPE_SMS**: SMS messaging agents (requires phone_number in E.164 format) - **MODEL_TYPE_WEBSOCKET**: WebSocket voice agents (requires metadata.endpoint wss:// URL in direct mode; metadata.initialization_json is optional) - **MODEL_TYPE_OPENAI_REALTIME**: OpenAI Realtime voice-to-voice agents - **MODEL_TYPE_GEMINI_REALTIME**: Gemini Live voice-to-voice agents - **MODEL_TYPE_GROK_REALTIME**: Grok (xAI) Voice Agent voice-to-voice agents enum: - MODEL_TYPE_VOICE - MODEL_TYPE_OUTBOUND_VOICE - MODEL_TYPE_CHAT - MODEL_TYPE_CHAT_A2A - MODEL_TYPE_CHAT_WEBSOCKET - MODEL_TYPE_SMS - MODEL_TYPE_WEBSOCKET - MODEL_TYPE_OPENAI_REALTIME - MODEL_TYPE_GEMINI_REALTIME - MODEL_TYPE_GROK_REALTIME example: MODEL_TYPE_VOICE AgentResource: type: object description: > Agent configuration resource. Note: The `active` field (soft delete status) is managed internally and not exposed in API responses. required: - customer_agent_id properties: id: type: string description: Agent resource ID pattern: ^[A-Za-z0-9]{22}$ example: abc123def456ghi789jklm customer_agent_id: type: string description: >- Customer-supplied external id for the agent. Defaults to `id` when not set at creation. example: my-support-agent display_name: type: string description: Human-readable agent name minLength: 1 maxLength: 200 example: Customer Support Agent model_type: $ref: '#/components/schemas/SimulatorType' phone_number: type: string nullable: true description: Phone number in E.164 format or SIP address for voice/SMS agents maxLength: 200 example: '+1234567890' endpoint: type: string nullable: true description: Custom API endpoint URL maxLength: 200 example: https://api.example.com/agent prompt: type: string nullable: true description: Agent instructions/system prompt example: You are a helpful customer support agent... language: type: string nullable: true description: Primary language for the agent example: en attributes: type: object nullable: true description: >- Free-form agent attributes; referenceable in metric prompts as `{{agent.}}`. additionalProperties: true example: company_name: Acme Corp tier: enterprise metadata: type: object description: Simulator-specific configuration (JSONB) additionalProperties: true example: voice: alloy model: gpt-realtime-2 workflows: type: object description: Workflow configuration (JSONB) additionalProperties: true example: {} metric_ids: type: array description: Associated metric IDs items: type: string example: - abc123def456ghi789jklm - def456ghi789jklmabc123 test_set_ids: type: array description: Associated test set IDs items: type: string example: - gT5wq2Hn knowledge_base_ids: type: array description: >- Associated knowledge base entry IDs (read-only, derived from reverse FK) readOnly: true items: type: string example: [] tags: type: array description: Tags associated with this agent items: type: string default: [] example: - production - voice create_time: type: string format: date-time description: Creation timestamp (ISO 8601) example: '2025-10-14T12:00:00Z' update_time: type: string format: date-time nullable: true description: Last update timestamp (ISO 8601) example: '2025-10-15T14:30:00Z' examples: UpdateAgentPartial: summary: Partial update (only some fields) value: display_name: Updated Agent Name prompt: Updated instructions... metadata: updated: true UpdateAgentClearFields: summary: Clear optional fields value: metadata: {} metric_ids: [] workflows: {} AgentUpdated: summary: Agent updated successfully value: agent: id: abc123def456ghi789jklm customer_agent_id: abc123def456ghi789jklm display_name: Updated Agent Name model_type: MODEL_TYPE_VOICE phone_number: '+1234567890' endpoint: https://api.example.com/agent prompt: Updated instructions... metadata: updated: true workflows: {} metric_ids: [] test_set_ids: [] knowledge_base_ids: [] create_time: '2025-10-14T12:00:00Z' update_time: '2025-10-23T16:45:00Z' AgentNotFoundError: summary: Agent not found value: error: code: NOT_FOUND message: Agent not found details: - field: agent_id description: Agent not found or not accessible by your organization responses: Unauthorized: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UNAUTHENTICATED message: Authentication failed details: - field: x-api-key description: Invalid or missing API key InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INTERNAL message: Internal server error details: - description: An unexpected error occurred securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key for authentication ````