---
title: "Update A Registered Agent"
method: PATCH
path: "/v1/orchestrate/agents/{id}"
tags: ["Agents"]
---

# Update A Registered Agent

`PATCH /v1/orchestrate/agents/{id}`

Updates an existing agent by id.

## Path parameters

- `id` string, required

## Request body

- PatchAgent — Schema for updating an existing agent.
  - `name` string, nullable — Name of the agent
  - `description` string, nullable — Updated description
  - `instructions` string, nullable — Updated instructions
  - `tools` string[], nullable — Updated list of tool names
  - `collaborators` string[], nullable — Updated list of collaborator names
  - `llm` string, nullable — Updated LLM identifier
  - `style` 'default' | 'react' | 'planner' | 'custom' | 'react_intrinsic' | 'experimental_customer_care' | 'code_act'
  - `supported_apps` SupportedApp[], nullable — Supported apps of the agent
  - `glossary` string[], nullable — List of glossary available to the agent
  - `guidelines` Guideline[], nullable — List of guidelines for the agent behavior
    - `display_name` string, nullable — Display name of the guideline
    - `condition` string, required — Condition when the guideline should be applied
    - `action` string, required — Action to take when the condition is met
    - `tool` string, nullable — The tool id use for this guideline
  - `knowledge_base` string[], nullable — List of knowledge_base available to the agent
  - `hidden` boolean — To show or hide agent when agents are listed
  - `display_name` string, nullable — Display name of the agent
  - `structured_output` object, nullable — JSON schema defining the structure for agent responses
  - `custom_join_tool` string, nullable — Reference to a Python tool that will be used for custom synthesis of task results
  - `additional_properties` AgentAdditionalPropertiesIn — A specification for creating settings within an agent. Validation runs for Input.
    - `starter_prompts` AgentCustomizedPromptsIn
      - `customize` AgentPrompt[] — list of starter prompts of the agent
        - `id` string — Unique identifier for the prompt
        - `title` string, required — Title of the prompt
        - `subtitle` string — description of the prompt
        - `prompt` string, required — contents of the prompt
        - `state` string — active/inactivate
    - `welcome_content` AgentWelcomeContentIn
      - `welcome_message` string, nullable — Welcome message
      - `description` string, nullable — Description
      - `is_default_voice_greeting` boolean — is the welcome message the default voice greeting
    - `icon` string — A raw SVG XML string (normalized from bytes / single- / double-escaped) that passes square-icon validation. When serialized, it's just a string.
    - `realtime_agent_settings` RealtimeAgentSettingsIn — Input model for creating/updating realtime agent settings
      - `enabled` boolean, nullable — Whether the realtime agent is enabled
    - `context_settings` ContextSettings — Context management settings for an agent.
      - `context_compaction_enabled` boolean, nullable — Enable context compaction
      - `context_compaction_threshold` integer, nullable — Token threshold for context compaction
      - `compaction_sliding_window` integer, nullable — Sliding window size for compaction
      - `large_message_threshold` integer, nullable — Token threshold for large message handling
      - `large_message_chunk_size` integer, nullable — Chunk size for large message processing
      - `large_message_target_summary` integer, nullable — Target summary size for large messages
      - `large_message_detect_structured` boolean, nullable — Enable structured data detection
  - `tags` string[], nullable — List of tags associated to agent
  - `voice_configuration_id` string, uuid, nullable — Voice configuration for the agent
  - `chat_with_docs` ChatWithDocsConfig
    - `enabled` boolean — Controls if the Chat with Documents feature is enabled for this agent
    - `supports_full_document` boolean — Controls if the Agent can request to use the full document. Only used if generation.enabled = false
    - `vector_index` KnowledgeBaseBuiltInVectorIndexConfig
      - `embeddings_model_name` string, nullable
      - `chunk_size` integer
      - `chunk_overlap` integer
      - `limit` integer
      - `extraction_strategy` 'express' | 'standard' | 'high_quality'
    - `generation` GenerationConfiguration — example { "model_id": "meta-llama/llama-3-1-70b-instruct", "prompt_instruction": "When the documents are in different languages, you should respond in english.", "max_docs_passed_to_llm": 5, "retrieval_confidence_threshold": "Lowest", "generated_response_length": "Moderate", "response_confidence_threshold": "Low", "display_text_no_results_found": "no docs found", "display_text_connectivity_issue": "conn failed", }
      - `model_id` string, nullable
      - `prompt_instruction` string
      - `max_docs_passed_to_llm` integer
      - `generated_response_length` 'Concise' | 'Moderate' | 'Verbose'
      - `display_text_no_results_found` string
      - `display_text_connectivity_issue` string
      - `idk_message` string
      - `enabled` boolean
    - `query_rewrite` QueryRewriteConfig — example { "enabled": True, "model_id": "meta-llama/llama-3-1-70b-instruct" }
      - `enabled` boolean
      - `model_id` string, nullable
    - `confidence_thresholds` ConfidenceThresholds
      - `retrieval_confidence_threshold` 'Off' | 'Lowest' | 'Low' | 'High' | 'Highest'
      - `response_confidence_threshold` 'Off' | 'Lowest' | 'Low' | 'High' | 'Highest'
    - `citations` CitationsConfig — example: { "citation_title": "how do i know", "citations_shown": 5, }
      - `citation_title` string
      - `citations_shown` integer
    - `hap_filtering` HAPFiltering — example { "output": { "enabled": True, "threshold": 0.7, } }
      - `output` HAPFilteringConfig
        - `enabled` boolean
        - `threshold` number
    - `query_source` 'SessionHistory' | 'Agent'
    - `agent_query_description` string
  - `context_access_enabled` boolean, nullable — Enable access to context variables for this agent
  - `connection_ids` string[], nullable — List of connection IDs for direct agent-to-connection bindings
  - `context_variables` string[], nullable — List of context variable names that this agent can access
  - `hide_reasoning` boolean, nullable — Enable/disable reasoning trace
  - `workspace_id` string, uuid, nullable — ID of the workspace that owns this agent
  - `llm_config` ModelConfig
    - `decoding_method` string, nullable
    - `prompt` union
      - string
      - string[]
    - `max_tokens` integer, nullable
    - `max_completion_tokens` integer, nullable
    - `temperature` number, nullable
    - `top_p` number, nullable
    - `n` integer, nullable
    - `stream` boolean, nullable
    - `logprobs` integer, nullable
    - `top_logprobs` boolean, nullable
    - `echo` boolean, nullable
    - `stop` union
      - string
      - string[]
    - `presence_penalty` number, nullable
    - `frequency_penalty` number, nullable
    - `best_of` integer, nullable
    - `logit_bias` object, nullable
    - `user` string, nullable
    - `context` string, nullable
    - `examples` Examples[], nullable
      - `input` unknown, required
      - `output` unknown, required
    - `top_k` integer, nullable
    - `response_format` ResponseFormat
      - `type` string, required
      - `json_schema` unknown
    - `seed` integer, nullable
    - `store` boolean, nullable
    - `metadata` object, nullable
    - `modalities` string[], nullable
    - `audio` AudioConfig
      - `voice` string, required
      - `format` string, required
    - `service_tier` string, nullable
    - `prediction` Prediction
      - `type` string, required
      - `content` union, required
        - PredictionContent[]
          - `type` string, required
          - `text` string, required
        - string
    - `safety_settings` unknown
    - `anthropic_beta` string, nullable
    - `anthropic_version` string, nullable
    - `thinking` Thinking
      - `type` string, nullable
      - `budget_tokens` integer, required
    - `space_id` string, nullable
    - `project_id` string, nullable
    - `reasoning_effort` string, nullable
    - `parallel_tool_calls` boolean, nullable
    - `disable_parallel_tool_use` boolean, nullable
    - `disable_tool_validation` boolean, nullable
    - `verbosity` string, nullable
    - `thinking_level` string, nullable
  - `plugins` Plugins
    - `agent_pre_invoke` Plugin[], nullable — Plugins to the invoke before agent
      - `plugin_id` string — Plugins to the invoke before agent
    - `agent_post_invoke` Plugin[], nullable — Plugins to the invoke after agent
      - `plugin_id` string — Plugins to the invoke before agent
  - `sync_tool_flow_interactions` boolean, nullable — Enable/disable syncing user interactions from tool flow to the agent
  - `toolkits` string[], nullable — Updated list of toolkit ids
  - `memory_enabled` boolean, nullable — Enable/disable agentic memory for this agent
  - `timeout_seconds` integer, nullable — Timeout in seconds for agent execution (min=120, max=900)
  - `custom_agents_metadata` object, nullable — Metadata for custom agents (language, framework, tool count, tool names, connection requirements)

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/ibm/apis/wxo-server-api.md) · [All operations](https://skmtc.net/ibm/apis/wxo-server-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ibm/wxo-server-api/versions/82c114c37196/schema)