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

# Update agent

> Partially update an agent's configuration. Omitted fields remain unchanged.

Active agents transition to `Updating` during the patch and return to `Active` once complete. If redeployment fails, the agent status is set to `Failed`.

Agents in `Inactive` or `Failed` states remain in their current state after a patch. To activate an updated agent, [promote it](/flow/reference/promote_v2_flow_agents__agent_id__promote_put) manually.

The `tool_ids` parameter accepts IDs for any tool type, including agent-as-tools. Agent-as-tools must be created before adding them to `tool_ids`. See [Agent as tool](/flow/sdk/agents/agent-as-tool) for setup instructions.


## OpenAPI

````yaml patch /v2/flow/agents/{agent_id}
openapi: 3.1.0
info:
  title: SeekrFlow API
  description: SeekrFlow API Documentation
  termsOfService: http://www.seekr.com/support
  contact:
    name: Seekr API Support
    url: http://www.seekr.com/contact
    email: contact@seekr.com
  version: 5.137.4
servers:
  - url: https://flow.seekr.com
    description: SeekrBuild server base URL
security: []
paths:
  /v2/flow/agents/{agent_id}:
    patch:
      tags:
        - Agents
      summary: Patch
      description: >-
        Partially updates an agent. Only explicitly provided fields are changed.


        On success, the agent and its descendants are redeployed.

        On deploy failure the agent status is set to FAILED.

        Tool ownership and model validation are enforced before any write
        occurs.
      operationId: patch_v2_flow_agents__agent_id__patch
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            title: Agent Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchAgentRequest'
            examples:
              preferred_tool_ids:
                summary: Preferred usage using tool_ids
                value:
                  name: My Agent
                  instructions: >-
                    You are a helpful assistant that can search files, browse
                    the web, and run Python code.
                  model_id: deployment-123
                  temperature: 0.4
                  reasoning_effort: medium
                  tool_ids:
                    - tool-123
                    - tool-456
              legacy_tools_deprecated:
                summary: Legacy usage using tools (deprecated)
                description: 'DEPRECATED: Use tool_ids instead.'
                value:
                  name: My Agent
                  instructions: >-
                    You are a helpful assistant that can search files, browse
                    the web, and run Python code.
                  model_id: deployment-123
                  temperature: 0.4
                  reasoning_effort: medium
                  tools:
                    - name: file_search
                      tool_env:
                        file_search_index: my-index
                        document_tool_desc: Search through documents
                        top_k: 10
                        score_threshold: 0.7
                    - name: web_search
                      tool_env:
                        web_search_tool_description: Search the web for current information
                    - name: run_python
                      tool_env:
                        run_python_tool_desc: Execute Python code
                        function_ids:
                          - func-123
                          - func-456
                    - name: agent_as_tool
                      agent_id: ag-123...
                      description: Description of subagent tool.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSchemaV2'
        '422':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    PatchAgentRequest:
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 256
            - type: 'null'
          title: Name
        instructions:
          anyOf:
            - type: string
              maxLength: 32768
            - type: 'null'
          title: Instructions
        model_id:
          anyOf:
            - type: string
              maxLength: 32768
            - type: 'null'
          title: Model Id
        planner_model_id:
          anyOf:
            - type: string
              maxLength: 32768
            - type: 'null'
          title: Planner Model Id
        tool_model_id:
          anyOf:
            - type: string
              maxLength: 32768
            - type: 'null'
          title: Tool Model Id
        output:
          anyOf:
            - $ref: '#/components/schemas/AgentOutputConfig'
            - type: 'null'
          description: >-
            Optional configuration for the agent's final response. Overrides the
            top-level settings for response generation.
        temperature:
          anyOf:
            - type: number
              maximum: 2
              minimum: 0
            - type: 'null'
          title: Temperature
          description: >-
            Controls the predictability of the agent's reasoning. Accepts a
            value from `0` to `2`. Defaults to `0.6`. Lower values produce more
            consistent results, and higher values introduce more variation.
        tool_ids:
          anyOf:
            - items:
                type: string
                maxLength: 32768
              type: array
            - type: 'null'
          title: Tool Ids
        reasoning_effort:
          anyOf:
            - $ref: '#/components/schemas/ReasoningEffort'
            - type: 'null'
      additionalProperties: false
      type: object
      title: PatchAgentRequest
    AgentSchemaV2:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        instructions:
          type: string
          title: Instructions
        status:
          $ref: '#/components/schemas/AgentStatus'
        model_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Id
        planner_model_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Planner Model Id
        tool_model_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Model Id
        output:
          anyOf:
            - $ref: '#/components/schemas/AgentOutputConfig'
            - type: 'null'
        temperature:
          anyOf:
            - type: number
              maximum: 2
              minimum: 0
            - type: 'null'
          title: Temperature
        reasoning_effort:
          $ref: '#/components/schemas/ReasoningEffort'
        planner_temperature:
          anyOf:
            - type: number
              maximum: 2
              minimum: 0
            - type: 'null'
          title: Planner Temperature
        user_id:
          type: string
          title: User Id
        team_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Team Id
        tools:
          items:
            oneOf:
              - $ref: >-
                  #/components/schemas/llm_training__agents__tools__standalone__schemas__FileSearch
              - $ref: >-
                  #/components/schemas/llm_training__agents__tools__standalone__schemas__RunPython
              - $ref: >-
                  #/components/schemas/llm_training__agents__tools__standalone__schemas__WebSearch
              - $ref: >-
                  #/components/schemas/llm_training__agents__tools__standalone__schemas__AgentAsTool
              - $ref: >-
                  #/components/schemas/llm_training__agents__tools__standalone__schemas__MCPConnectorTool
            discriminator:
              propertyName: type
              mapping:
                agent_as_tool: >-
                  #/components/schemas/llm_training__agents__tools__standalone__schemas__AgentAsTool
                file_search: >-
                  #/components/schemas/llm_training__agents__tools__standalone__schemas__FileSearch
                mcp_connector: >-
                  #/components/schemas/llm_training__agents__tools__standalone__schemas__MCPConnectorTool
                run_python: >-
                  #/components/schemas/llm_training__agents__tools__standalone__schemas__RunPython
                web_search: >-
                  #/components/schemas/llm_training__agents__tools__standalone__schemas__WebSearch
          type: array
          title: Tools
          description: >-
            The tools available to the agent. Each item configures one tool and
            must match one of the supported tool types: file search, run Python,
            web search, agent-as-tool, or MCP connector.
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        last_deployed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Deployed At
        active_duration:
          type: integer
          minimum: 0
          title: Active Duration
          default: 0
      type: object
      required:
        - id
        - name
        - instructions
        - status
        - reasoning_effort
        - user_id
        - team_id
        - created_at
        - updated_at
      title: AgentSchemaV2
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentOutputConfig:
      properties:
        frequency:
          anyOf:
            - $ref: '#/components/schemas/AgentOutputFrequency'
            - type: 'null'
          description: >-
            When the agent produces a written response: `always`, `automatic`
            (the agent decides), or `never`.
        instructions:
          anyOf:
            - type: string
              maxLength: 32768
            - type: 'null'
          title: Instructions
          description: >-
            Instructions for generating the agent's final response. When set,
            the top-level `instructions` guide only the agent's reasoning, and
            these guide the response.
        model_id:
          anyOf:
            - type: string
              maxLength: 32768
            - type: 'null'
          title: Model Id
          description: >-
            The model used to generate the agent's final response, overriding
            the top-level `model_id`. Can be a base model or fine-tuned model.
        temperature:
          anyOf:
            - type: number
              maximum: 2
              minimum: 0
            - type: 'null'
          title: Temperature
          description: >-
            Controls the predictability of the agent's final response. Accepts a
            value from `0` to `2`. Defaults to `0.6`.
      type: object
      title: AgentOutputConfig
    ReasoningEffort:
      type: string
      enum:
        - low
        - medium
        - high
        - speed_optimized
        - performance_optimized
      title: ReasoningEffort
      description: >-
        Controls how much reasoning the agent uses when working through a
        request. Accepts `low`, `medium`, or `high`, where higher levels produce
        more thorough reasoning. The `speed_optimized` and
        `performance_optimized` values are only supported for backward
        compatibility. `speed_optimized` maps to `low`, and
        `performance_optimized` maps to `high`.
    AgentStatus:
      type: string
      enum:
        - Inactive
        - Pending
        - Active
        - Updating
        - Failed
      title: AgentStatus
    llm_training__agents__tools__standalone__schemas__FileSearch:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        type:
          type: string
          const: file_search
          title: Type
          default: file_search
        config:
          $ref: '#/components/schemas/FileSearchConfig'
      type: object
      required:
        - id
        - name
        - config
      title: FileSearch
      description: >-
        Configuration for the file search tool: semantic search and retrieval
        across the agent's vector databases.
    llm_training__agents__tools__standalone__schemas__RunPython:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        type:
          type: string
          const: run_python
          title: Type
          default: run_python
        config:
          $ref: '#/components/schemas/RunPythonConfig'
          default: {}
      type: object
      required:
        - id
        - name
      title: RunPython
      description: >-
        Configuration for the run Python tool, which lets the agent execute
        developer-defined Python functions.
    llm_training__agents__tools__standalone__schemas__WebSearch:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        type:
          type: string
          const: web_search
          title: Type
          default: web_search
      type: object
      required:
        - id
        - name
      title: WebSearch
      description: >-
        Configuration for the web search tool: real-time information retrieval
        from web sources.
    llm_training__agents__tools__standalone__schemas__AgentAsTool:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        type:
          type: string
          const: agent_as_tool
          title: Type
          default: agent_as_tool
        config:
          $ref: '#/components/schemas/AgentAsToolConfig'
      type: object
      required:
        - id
        - name
        - config
      title: AgentAsTool
      description: >-
        Configuration for an agent-as-tool, which delegates subtasks to another
        agent and returns the result to the supervisor.
    llm_training__agents__tools__standalone__schemas__MCPConnectorTool:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        type:
          type: string
          const: mcp_connector
          title: Type
          default: mcp_connector
        config:
          $ref: '#/components/schemas/MCPConnectorToolResponseConfig'
      type: object
      required:
        - id
        - name
        - config
      title: MCPConnectorTool
      description: >-
        Configuration for the MCP connector tool, which connects the agent to
        external MCP providers through a secure gateway with OAuth-based
        authentication.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    AgentOutputFrequency:
      type: string
      enum:
        - always
        - never
        - automatic
      title: AgentOutputFrequency
    FileSearchConfig:
      properties:
        FILE_SEARCH_INDEX:
          type: string
          maxLength: 32768
          minLength: 1
          title: File Search Index
        EMBEDDING_MODEL:
          anyOf:
            - type: string
              maxLength: 32768
              minLength: 1
            - type: 'null'
          title: Embedding Model
        TOP_K:
          type: integer
          maximum: 100
          minimum: 1
          title: Top K
          description: Top K must be >= 1 and <= 100
          default: 10
        SCORE_THRESHOLD:
          type: number
          exclusiveMaximum: 1
          minimum: 0
          title: Score Threshold
          description: Score must be ≥ 0.0 and < 1.0
          default: 0
      additionalProperties: false
      type: object
      required:
        - FILE_SEARCH_INDEX
      title: FileSearchConfig
    RunPythonConfig:
      properties:
        FUNCTION_IDS:
          anyOf:
            - items:
                type: string
                maxLength: 32768
                minLength: 1
              type: array
            - type: 'null'
          title: Function Ids
      additionalProperties: false
      type: object
      title: RunPythonConfig
    AgentAsToolConfig:
      properties:
        AGENT_ID:
          type: string
          maxLength: 32768
          minLength: 1
          title: Agent Id
      additionalProperties: false
      type: object
      required:
        - AGENT_ID
      title: AgentAsToolConfig
    MCPConnectorToolResponseConfig:
      properties:
        URL:
          type: string
          maxLength: 32768
          minLength: 1
          title: Url
        TRANSPORT:
          type: string
          enum:
            - sse
            - streamable-http
          title: Transport
          default: streamable-http
        AUTHORIZATION_URL:
          anyOf:
            - type: string
              maxLength: 32768
              minLength: 1
            - type: 'null'
          title: Authorization Url
      additionalProperties: false
      type: object
      required:
        - URL
      title: MCPConnectorToolResponseConfig
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: >-
        Your Seekr API key, sent in the Authorization header with no 'Bearer'
        prefix.
      in: header
      name: Authorization

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.