> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update A Registered Agent

> Updates an existing agent by id.



## OpenAPI

````yaml patch /v1/orchestrate/agents/{id}
openapi: 3.1.0
info:
  title: WxO Server API
  summary: API for the next gen watsonx Orchestrate stack
  description: >+

    The watsonx Orchestrate Server provides a set of APIs to power the watsonx
    Orchestrate AI assistant. This includes the following core services:


    * Orchestrate Assistant - a built-in AI assistant that powers the
    Orchestrate end-user experience.

    * Custom Assistants - a service layer for interacting with existing AI
    assistatns (such as those in watsonx Assistant).

    * Message Threads - a chat history and async message tracking store.

    * Document Store - manage collections of documents in nearly any format
    including text, pdf, html and many more.

    * Information Extraction - automatically extract clean text and images from
    any document in the Document Store.  Also extract other useful metadata like
    questions answered, keywords, and named entities.

    * Embedding - generate vector embeddings for text and images in the Document
    Store.

    * Vector Index and Retrieval - automatically index documents with rich
    metadata for vector search or hybrid search.

    * Search Engine - create a Gen AI powered search engine that works like Bing
    or Google.

    * Query Engine - configure your own RAG (Retrieval Augmented Generation)
    engine supporting advanced retrieval patterns and automated data management.

    * Model Proxy - create your own LLM model endpoints for chat completions and
    embeddings.  Supports IBM watsonx.ai, IBM BAM, OpenAI, MistralAI, or Ollama
    for local models.


    WxO API Server utilizes the following open source projects:


    * [PostgreSQL](https://www.postgresql.org/)

    * [PGVector](https://github.com/pgvector/pgvector)

    * [LlamaIndex](https://docs.llamaindex.ai/en/stable/)

    * [LangChain](https://python.langchain.com/docs/get_started/introduction)

    * [FastAPI](https://fastapi.tiangolo.com/)

    * [Unstructured](https://unstructured.io/)

    * [Celery](https://docs.celeryproject.org/en/stable/)

  version: 0.1.0
servers:
  - url: https://{api_endpoint}
    description: version
security: []
paths:
  /v1/orchestrate/agents/{id}:
    patch:
      tags:
        - Agents
      summary: Update A Registered Agent
      description: Updates an existing agent by id.
      operationId: Update_a_registered_agent__v1_orchestrate_agents__id__patch
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchAgent'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    PatchAgent:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Name of the agent
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Updated description
        instructions:
          anyOf:
            - type: string
            - type: 'null'
          title: Instructions
          description: Updated instructions
        tools:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tools
          description: Updated list of tool names
        collaborators:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Collaborators
          description: Updated list of collaborator names
        llm:
          anyOf:
            - type: string
            - type: 'null'
          title: Llm
          description: Updated LLM identifier
        style:
          anyOf:
            - $ref: '#/components/schemas/AgentStyle'
            - type: 'null'
          description: Style of the agent
        supported_apps:
          anyOf:
            - items:
                $ref: '#/components/schemas/SupportedApp'
              type: array
            - type: 'null'
          title: Supported Apps
          description: Supported apps of the agent
        glossary:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Glossary
          description: List of glossary available to the agent
          default: []
        guidelines:
          anyOf:
            - items:
                $ref: '#/components/schemas/Guideline'
              type: array
            - type: 'null'
          title: Guidelines
          description: List of guidelines for the agent behavior
        knowledge_base:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Knowledge Base
          description: List of knowledge_base available to the agent
          default: []
        hidden:
          type: boolean
          title: Hidden
          description: To show or hide agent when agents are listed
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Display Name
          description: Display name of the agent
        structured_output:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Structured Output
          description: JSON schema defining the structure for agent responses
        custom_join_tool:
          anyOf:
            - type: string
            - type: 'null'
          title: Custom Join Tool
          description: >-
            Reference to a Python tool that will be used for custom synthesis of
            task results
        additional_properties:
          anyOf:
            - $ref: '#/components/schemas/AgentAdditionalPropertiesIn'
            - type: 'null'
          description: Agent Additional Settings
        tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tags
          description: List of tags associated to agent
          default: []
        voice_configuration_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Voice Configuration Id
          description: Voice configuration for the agent
        chat_with_docs:
          anyOf:
            - $ref: '#/components/schemas/ChatWithDocsConfig'
            - type: 'null'
          description: Chat with Documents config for Agent
        context_access_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Context Access Enabled
          description: Enable access to context variables for this agent
        connection_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Connection Ids
          description: List of connection IDs for direct agent-to-connection bindings
        context_variables:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Context Variables
          description: List of context variable names that this agent can access
        hide_reasoning:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Hide Reasoning
          description: Enable/disable reasoning trace
        workspace_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Workspace Id
          description: ID of the workspace that owns this agent
        llm_config:
          anyOf:
            - $ref: '#/components/schemas/ModelConfig'
            - type: 'null'
        plugins:
          anyOf:
            - $ref: '#/components/schemas/Plugins'
            - type: 'null'
          description: Plugins and hook points associated to the agents
        sync_tool_flow_interactions:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Sync Tool Flow Interactions
          description: Enable/disable syncing user interactions from tool flow to the agent
        toolkits:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Toolkits
          description: Updated list of toolkit ids
        memory_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Memory Enabled
          description: Enable/disable agentic memory for this agent
        timeout_seconds:
          anyOf:
            - type: integer
            - type: 'null'
          title: Timeout Seconds
          description: Timeout in seconds for agent execution (min=120, max=900)
          max: 900
          min: 120
        custom_agents_metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Custom Agents Metadata
          description: >-
            Metadata for custom agents (language, framework, tool count, tool
            names, connection requirements)
      type: object
      title: PatchAgent
      description: Schema for updating an existing agent.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentStyle:
      type: string
      enum:
        - default
        - react
        - planner
        - custom
        - react_intrinsic
        - experimental_customer_care
        - code_act
      title: AgentStyle
    SupportedApp:
      type: string
      enum:
        - slack/askhr
      title: SupportedApp
    Guideline:
      properties:
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Display Name
          description: Display name of the guideline
        condition:
          type: string
          title: Condition
          description: Condition when the guideline should be applied
        action:
          type: string
          title: Action
          description: Action to take when the condition is met
        tool:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool
          description: The tool id use for this guideline
      type: object
      required:
        - condition
        - action
      title: Guideline
      description: Schema for an agent guideline.
    AgentAdditionalPropertiesIn:
      properties:
        starter_prompts:
          anyOf:
            - $ref: '#/components/schemas/AgentCustomizedPromptsIn'
            - type: 'null'
          description: Agent Starter Prompts
        welcome_content:
          anyOf:
            - $ref: '#/components/schemas/AgentWelcomeContentIn'
            - type: 'null'
          description: Agent Welcome Message
        icon:
          anyOf:
            - $ref: '#/components/schemas/AgentSvgIcon'
            - type: 'null'
          description: Agent Icon (SVG)
        realtime_agent_settings:
          anyOf:
            - $ref: '#/components/schemas/RealtimeAgentSettingsIn'
            - type: 'null'
          description: Realtime Agent Settings
        context_settings:
          anyOf:
            - $ref: '#/components/schemas/ContextSettings'
            - type: 'null'
          description: Context management settings
      type: object
      title: AgentAdditionalPropertiesIn
      description: |-
        A specification for creating settings within an agent.
        Validation runs for Input.
    ChatWithDocsConfig:
      properties:
        enabled:
          type: boolean
          title: Enabled
          description: >-
            Controls if the Chat with Documents feature is enabled for this
            agent
          default: false
        supports_full_document:
          type: boolean
          title: Supports Full Document
          description: >-
            Controls if the Agent can request to use the full document. Only
            used if generation.enabled = false
          default: true
        vector_index:
          $ref: '#/components/schemas/KnowledgeBaseBuiltInVectorIndexConfig'
        generation:
          $ref: '#/components/schemas/GenerationConfiguration'
        query_rewrite:
          $ref: '#/components/schemas/QueryRewriteConfig'
        confidence_thresholds:
          $ref: '#/components/schemas/ConfidenceThresholds'
        citations:
          $ref: '#/components/schemas/CitationsConfig'
        hap_filtering:
          $ref: '#/components/schemas/HAPFiltering'
        query_source:
          $ref: '#/components/schemas/QuerySource'
          default: Agent
        agent_query_description:
          type: string
          title: Agent Query Description
          default: The query to search for in the knowledge base
      type: object
      title: ChatWithDocsConfig
    ModelConfig:
      properties:
        decoding_method:
          anyOf:
            - type: string
            - type: 'null'
          title: Decoding Method
        prompt:
          anyOf:
            - type: string
            - items:
                type: string
              type: array
            - type: 'null'
          title: Prompt
        max_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Tokens
        max_completion_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Completion Tokens
        temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Temperature
        top_p:
          anyOf:
            - type: number
            - type: 'null'
          title: Top P
        'n':
          anyOf:
            - type: integer
            - type: 'null'
          title: 'N'
        stream:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Stream
        logprobs:
          anyOf:
            - type: integer
            - type: 'null'
          title: Logprobs
        top_logprobs:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Top Logprobs
        echo:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Echo
        stop:
          anyOf:
            - type: string
            - items:
                type: string
              type: array
            - type: 'null'
          title: Stop
        presence_penalty:
          anyOf:
            - type: number
            - type: 'null'
          title: Presence Penalty
        frequency_penalty:
          anyOf:
            - type: number
            - type: 'null'
          title: Frequency Penalty
        best_of:
          anyOf:
            - type: integer
            - type: 'null'
          title: Best Of
        logit_bias:
          anyOf:
            - additionalProperties:
                type: number
              type: object
            - type: 'null'
          title: Logit Bias
        user:
          anyOf:
            - type: string
            - type: 'null'
          title: User
        context:
          anyOf:
            - type: string
            - type: 'null'
          title: Context
        examples:
          anyOf:
            - items:
                $ref: '#/components/schemas/Examples'
              type: array
            - type: 'null'
          title: Examples
        top_k:
          anyOf:
            - type: integer
            - type: 'null'
          title: Top K
        response_format:
          anyOf:
            - $ref: '#/components/schemas/ResponseFormat'
            - type: 'null'
        seed:
          anyOf:
            - type: integer
            - type: 'null'
          title: Seed
        store:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Store
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
        modalities:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Modalities
        audio:
          anyOf:
            - $ref: '#/components/schemas/AudioConfig'
            - type: 'null'
        service_tier:
          anyOf:
            - type: string
            - type: 'null'
          title: Service Tier
        prediction:
          anyOf:
            - $ref: '#/components/schemas/Prediction'
            - type: 'null'
        safety_settings:
          anyOf:
            - {}
            - type: 'null'
          title: Safety Settings
        anthropic_beta:
          anyOf:
            - type: string
            - type: 'null'
          title: Anthropic Beta
        anthropic_version:
          anyOf:
            - type: string
            - type: 'null'
          title: Anthropic Version
        thinking:
          anyOf:
            - $ref: '#/components/schemas/Thinking'
            - type: 'null'
        space_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Space Id
        project_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Project Id
        reasoning_effort:
          anyOf:
            - type: string
            - type: 'null'
          title: Reasoning Effort
        parallel_tool_calls:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Parallel Tool Calls
        disable_parallel_tool_use:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Disable Parallel Tool Use
        disable_tool_validation:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Disable Tool Validation
        verbosity:
          anyOf:
            - type: string
            - type: 'null'
          title: Verbosity
        thinking_level:
          anyOf:
            - type: string
            - type: 'null'
          title: Thinking Level
      additionalProperties: false
      type: object
      title: ModelConfig
    Plugins:
      properties:
        agent_pre_invoke:
          anyOf:
            - items:
                $ref: '#/components/schemas/Plugin'
              type: array
            - type: 'null'
          title: Agent Pre Invoke
          description: Plugins to the invoke before agent
        agent_post_invoke:
          anyOf:
            - items:
                $ref: '#/components/schemas/Plugin'
              type: array
            - type: 'null'
          title: Agent Post Invoke
          description: Plugins to the invoke after agent
      type: object
      title: Plugins
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    AgentCustomizedPromptsIn:
      properties:
        customize:
          items:
            $ref: '#/components/schemas/AgentPrompt'
          type: array
          title: Customize
          description: list of starter prompts of the agent
      type: object
      title: AgentCustomizedPromptsIn
    AgentWelcomeContentIn:
      properties:
        welcome_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Welcome Message
          description: Welcome message
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Description
        is_default_voice_greeting:
          type: boolean
          title: Is Default Voice Greeting
          description: is the welcome message the default voice greeting
          default: false
      type: object
      title: AgentWelcomeContentIn
    AgentSvgIcon:
      type: string
      title: AgentSvgIcon
      description: |-
        A raw SVG XML string (normalized from bytes / single- / double-escaped)
        that passes square-icon validation. When serialized, it's just a string.
    RealtimeAgentSettingsIn:
      properties:
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enabled
          description: Whether the realtime agent is enabled
      type: object
      title: RealtimeAgentSettingsIn
      description: Input model for creating/updating realtime agent settings
    ContextSettings:
      properties:
        context_compaction_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Context Compaction Enabled
          description: Enable context compaction
        context_compaction_threshold:
          anyOf:
            - type: integer
            - type: 'null'
          title: Context Compaction Threshold
          description: Token threshold for context compaction
        compaction_sliding_window:
          anyOf:
            - type: integer
            - type: 'null'
          title: Compaction Sliding Window
          description: Sliding window size for compaction
        large_message_threshold:
          anyOf:
            - type: integer
            - type: 'null'
          title: Large Message Threshold
          description: Token threshold for large message handling
        large_message_chunk_size:
          anyOf:
            - type: integer
            - type: 'null'
          title: Large Message Chunk Size
          description: Chunk size for large message processing
        large_message_target_summary:
          anyOf:
            - type: integer
            - type: 'null'
          title: Large Message Target Summary
          description: Target summary size for large messages
        large_message_detect_structured:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Large Message Detect Structured
          description: Enable structured data detection
      type: object
      title: ContextSettings
      description: Context management settings for an agent.
    KnowledgeBaseBuiltInVectorIndexConfig:
      properties:
        embeddings_model_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Embeddings Model Name
        chunk_size:
          type: integer
          title: Chunk Size
          default: 400
        chunk_overlap:
          type: integer
          title: Chunk Overlap
          default: 50
        limit:
          type: integer
          title: Limit
          default: 10
        extraction_strategy:
          $ref: '#/components/schemas/ExtractionStrategy'
          default: standard
      type: object
      title: KnowledgeBaseBuiltInVectorIndexConfig
    GenerationConfiguration:
      properties:
        model_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Id
        prompt_instruction:
          type: string
          title: Prompt Instruction
          default: ''
        max_docs_passed_to_llm:
          type: integer
          title: Max Docs Passed To Llm
          default: 5
        generated_response_length:
          $ref: '#/components/schemas/GeneratedResponseLength'
          default: Moderate
        display_text_no_results_found:
          type: string
          title: Display Text No Results Found
          default: >-
            I searched my knowledge base, but did not find anything related to
            your query
        display_text_connectivity_issue:
          type: string
          title: Display Text Connectivity Issue
          default: >-
            I might have information related to your query to share, but am
            unable to connect to my knowledge base at the moment
        idk_message:
          type: string
          title: Idk Message
          default: I'm afraid I don't understand. Please rephrase your question.
        enabled:
          type: boolean
          title: Enabled
          default: false
      type: object
      title: GenerationConfiguration
      description: |-
        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",
        }
    QueryRewriteConfig:
      properties:
        enabled:
          type: boolean
          title: Enabled
          default: true
        model_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Id
      type: object
      title: QueryRewriteConfig
      description: |-
        example

        {
            "enabled": True,
            "model_id": "meta-llama/llama-3-1-70b-instruct"
        }
    ConfidenceThresholds:
      properties:
        retrieval_confidence_threshold:
          $ref: '#/components/schemas/RetrievalConfidenceThreshold'
          default: Lowest
        response_confidence_threshold:
          $ref: '#/components/schemas/ResponseConfidenceThreshold'
          default: Lowest
      type: object
      title: ConfidenceThresholds
    CitationsConfig:
      properties:
        citation_title:
          type: string
          title: Citation Title
          default: How do we know?
        citations_shown:
          type: integer
          title: Citations Shown
          default: -1
      type: object
      title: CitationsConfig
      description: |-
        example:
        {
            "citation_title": "how do i know",
            "citations_shown": 5,
        }
    HAPFiltering:
      properties:
        output:
          $ref: '#/components/schemas/HAPFilteringConfig'
      type: object
      title: HAPFiltering
      description: |-
        example
        {
            "output": {
                "enabled": True,
                "threshold": 0.7,
            }
        }
    QuerySource:
      type: string
      enum:
        - SessionHistory
        - Agent
      title: QuerySource
    Examples:
      properties:
        input:
          title: Input
        output:
          title: Output
      type: object
      required:
        - input
        - output
      title: Examples
    ResponseFormat:
      properties:
        type:
          type: string
          title: Type
        json_schema:
          anyOf:
            - {}
            - type: 'null'
          title: Json Schema
      type: object
      required:
        - type
      title: ResponseFormat
    AudioConfig:
      properties:
        voice:
          type: string
          title: Voice
        format:
          type: string
          title: Format
      type: object
      required:
        - voice
        - format
      title: AudioConfig
    Prediction:
      properties:
        type:
          type: string
          title: Type
        content:
          anyOf:
            - items:
                $ref: '#/components/schemas/PredictionContent'
              type: array
            - type: string
          title: Content
      type: object
      required:
        - type
        - content
      title: Prediction
    Thinking:
      properties:
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
        budget_tokens:
          type: integer
          title: Budget Tokens
      type: object
      required:
        - budget_tokens
      title: Thinking
    Plugin:
      properties:
        plugin_id:
          type: string
          title: Plugin Id
          description: Plugins to the invoke before agent
      type: object
      title: Plugin
    AgentPrompt:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the prompt
        title:
          type: string
          title: Title
          description: Title of the prompt
        subtitle:
          type: string
          title: Subtitle
          description: description of the prompt
        prompt:
          type: string
          title: Prompt
          description: contents of the prompt
        state:
          type: string
          title: State
          description: active/inactivate
      type: object
      required:
        - title
        - prompt
      title: AgentPrompt
    ExtractionStrategy:
      type: string
      enum:
        - express
        - standard
        - high_quality
      title: ExtractionStrategy
    GeneratedResponseLength:
      type: string
      enum:
        - Concise
        - Moderate
        - Verbose
      title: GeneratedResponseLength
    RetrievalConfidenceThreshold:
      type: string
      enum:
        - 'Off'
        - Lowest
        - Low
        - High
        - Highest
      title: RetrievalConfidenceThreshold
    ResponseConfidenceThreshold:
      type: string
      enum:
        - 'Off'
        - Lowest
        - Low
        - High
        - Highest
      title: ResponseConfidenceThreshold
    HAPFilteringConfig:
      properties:
        enabled:
          type: boolean
          title: Enabled
          default: false
        threshold:
          type: number
          title: Threshold
          default: 0.5
      type: object
      title: HAPFilteringConfig
    PredictionContent:
      properties:
        type:
          type: string
          title: Type
        text:
          type: string
          title: Text
      type: object
      required:
        - type
        - text
      title: PredictionContent
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````