---
title: "Update agent"
method: PATCH
path: "/agents/{agent_id}"
tags: ["Agents"]
---

# Update agent

`PATCH /agents/{agent_id}`

## Request

- Base URL: `https://api.coval.dev/v1`
- URL: `https://api.coval.dev/v1/agents/{agent_id}`
- Auth: API key in header `x-api-key`

Update specific fields of an existing agent configuration.

## Path parameters

- `agent_id` string, required

## Request body

- UpdateAgentRequest: Fields to update on an agent.
  - `display_name` string: Human-readable agent name
  - `model_type` 'MODEL_TYPE_VOICE' | 'MODEL_TYPE_OUTBOUND_VOICE' | 'MODEL_TYPE_CHAT' | 'MODEL_TYPE_CHAT_A2A' | 'MODEL_TYPE_CHAT_WEBSOCKET' | 'MODEL_TYPE_EMAIL' | 'MODEL_TYPE_SMS' | 'MODEL_TYPE_WEBSOCKET' | 'MODEL_TYPE_SDK_WEBSOCKET' | 'MODEL_TYPE_LIVEKIT' | 'MODEL_TYPE_DAILY' | 'MODEL_TYPE_OPENAI_REALTIME' | 'MODEL_TYPE_GEMINI_REALTIME' | 'MODEL_TYPE_GROK_REALTIME' | 'MODEL_TYPE_DEEPGRAM_REALTIME': 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_EMAIL**: Email-based text agents - **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_SDK_WEBSOCKET**: Voice agents that connect outbound to the Cloudflare Durable Object relay using Coval Agent SDK. - **MODEL_TYPE_LIVEKIT**: LiveKit agents (requires metadata.generate_token_endpoint and metadata.livekit_url) - **MODEL_TYPE_DAILY**: Pipecat Cloud agents (requires metadata.pipecat_api_key and metadata.agent_name) - **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 - **MODEL_TYPE_DEEPGRAM_REALTIME**: Deepgram Voice Agent voice-to-voice agents
  - `phone_number` string, nullable: Phone number in E.164 format or SIP address for voice/SMS agents
  - `endpoint` string, nullable: Custom API endpoint URL
  - `prompt` string, nullable: Agent instructions/system prompt
  - `customer_agent_id` string: External identifier for the agent
  - `language` string, nullable: Primary language for the agent
  - `attributes` object, nullable: Free-form agent attributes
  - `metadata` object, nullable: Simulator-specific configuration
  - `workflows` object, nullable: Workflow configuration
  - `metric_ids` string[], nullable: Associated metric IDs
  - `test_set_ids` string[], nullable: Associated test set IDs
  - `tags` string[], nullable: Tags associated with the agent

## Response `200`

Agent updated successfully

- UpdateAgentResponse
  - `agent` AgentResource, required: Agent configuration resource. Note: The `active` field (soft delete status) is managed internally and not exposed in API responses.
    - `created_at` string, date-time, nullable, required: Authoring timestamp; null when unknown.
    - `created_by` string, nullable, required: Canonical author user ID; null when unknown.
    - `updated_at` string, date-time, nullable, required: Authoring timestamp; null when unknown.
    - `updated_by` string, nullable, required: Canonical author user ID; null when unknown.
    - `id` string, required: Agent resource ID
    - `customer_agent_id` string, required: Customer-supplied external id for the agent. Defaults to `id` when not set at creation.
    - `display_name` string, required: Human-readable agent name
    - `model_type` 'MODEL_TYPE_VOICE' | 'MODEL_TYPE_OUTBOUND_VOICE' | 'MODEL_TYPE_CHAT' | 'MODEL_TYPE_CHAT_A2A' | 'MODEL_TYPE_CHAT_WEBSOCKET' | 'MODEL_TYPE_EMAIL' | 'MODEL_TYPE_SMS' | 'MODEL_TYPE_WEBSOCKET' | 'MODEL_TYPE_SDK_WEBSOCKET' | 'MODEL_TYPE_OPENAI_REALTIME' | 'MODEL_TYPE_GEMINI_REALTIME' | 'MODEL_TYPE_GROK_REALTIME' | 'MODEL_TYPE_DEEPGRAM_REALTIME' | 'MODEL_TYPE_TEXT' | 'MODEL_TYPE_LIVEKIT' | 'MODEL_TYPE_DAILY' | 'MODEL_TYPE_NOOP' | 'MODEL_TYPE_OPENAI_ENDPOINT' | 'MODEL_TYPE_TRANSCRIPTION' | 'MODEL_TYPE_TTS' | 'MODEL_TYPE_VOICE_TO_VOICE', required: Agent type returned by the API. Responses can include active types as well as legacy types retained for existing agents. Only values in `SimulatorType` can be supplied when creating or changing an agent type.
    - `phone_number` string, nullable: Phone number in E.164 format or SIP address for voice/SMS agents
    - `endpoint` string, nullable: Custom API endpoint URL
    - `prompt` string, nullable: Agent instructions/system prompt
    - `language` string, nullable: Primary language for the agent
    - `attributes` object, nullable: Free-form agent attributes; referenceable in metric prompts as `{{agent.<key>}}`.
    - `metadata` object: Simulator-specific configuration (JSONB)
    - `workflows` object: Workflow configuration (JSONB)
    - `metric_ids` string[]: Associated metric IDs
    - `test_set_ids` string[]: Associated test set IDs
    - `knowledge_base_ids` string[]: Associated knowledge base entry IDs (read-only, derived from reverse FK)
    - `tags` string[]: Tags associated with this agent
    - `create_time` string, date-time, required: Creation timestamp (ISO 8601)
    - `update_time` string, date-time, nullable: Last update timestamp (ISO 8601)

## Other responses

- `400`: Invalid request body or validation failed
- `401`: Authentication failed
- `404`: Agent not found, inactive, or belongs to different organization
- `500`: Internal server error

---

[API](https://skmtc.dev/coval/apis/coval-agents-api.md) - [All operations](https://skmtc.dev/coval/apis/coval-agents-api/llms.txt) - [OpenAPI document](https://skmtc.dev/coval/apis/coval-agents-api/revisions/ba0291fe3911?raw)