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

# Update an agent



## OpenAPI

````yaml /api-reference/openapi.json put /v1/agents/{agent_id}
openapi: 3.1.0
info:
  title: Feather API
  description: >-
    Unified customer experience platform API. Manages identity, conversations,
    memory, agents, procedures, policies, model routing, knowledge bases,
    integrations, and runtime execution.
  version: 1.21.0
servers:
  - url: https://api-sandbox.featherhq.com
    description: Sandbox
  - url: http://localhost:8000
    description: Local dev
security: []
paths:
  /v1/agents/{agent_id}:
    put:
      tags:
        - agents
      summary: Update an agent
      operationId: updateAgent
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Agent Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    AgentUpdate:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
        knowledge_gap_analysis_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Knowledge Gap Analysis Enabled
        release_suite_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Release Suite Id
        release_gate_mode:
          anyOf:
            - $ref: '#/components/schemas/ReleaseGateMode'
            - type: 'null'
        release_gate_max_failures:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Release Gate Max Failures
      type: object
      title: AgentUpdate
    AgentResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        organization_id:
          type: string
          format: uuid
          title: Organization Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        active_revision_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Active Revision Id
        active_revision:
          anyOf:
            - $ref: '#/components/schemas/AgentRevisionResponse'
            - type: 'null'
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        platform_tools:
          additionalProperties: true
          type: object
          title: Platform Tools
        knowledge_gap_analysis_enabled:
          type: boolean
          title: Knowledge Gap Analysis Enabled
          default: true
        release_suite_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Release Suite Id
        release_gate_mode:
          $ref: '#/components/schemas/ReleaseGateMode'
          default: 'off'
        release_gate_max_failures:
          type: integer
          title: Release Gate Max Failures
          default: 0
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - organization_id
        - name
        - created_at
        - updated_at
      title: AgentResponse
    ErrorResponse:
      properties:
        error:
          type: string
          title: Error
        message:
          type: string
          title: Message
      type: object
      required:
        - error
        - message
      title: ErrorResponse
      description: Standard error response returned by all API error handlers.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ReleaseGateMode:
      type: string
      enum:
        - 'off'
        - advisory
        - blocking
      title: ReleaseGateMode
      description: >-
        Per-agent release-gate mode (ENG-727). ``off`` = no release checks;

        ``advisory`` = compute + display a verdict but never block activation;

        ``blocking`` = (Phase 2) refuse activation without a fresh passing
        verdict.

        Dormant in Phase 1 — only the Phase-2 activation gate reads it.
    AgentRevisionResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        agent_id:
          type: string
          format: uuid
          title: Agent Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        persona:
          anyOf:
            - type: string
            - type: 'null'
          title: Persona
        system_prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: System Prompt
        global_skill_ids:
          anyOf:
            - items:
                type: string
                format: uuid
              type: array
            - type: 'null'
          title: Global Skill Ids
        context_variables:
          anyOf:
            - items:
                $ref: '#/components/schemas/ContextVarSpec'
              type: array
            - type: 'null'
          title: Context Variables
        variable_defaults:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Variable Defaults
        tool_refs:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Tool Refs
        knowledge_base_refs:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Knowledge Base Refs
        policies_enabled:
          type: boolean
          title: Policies Enabled
          default: true
        policy_refs:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Policy Refs
        channel_specific_config:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/ChannelConfig'
              propertyNames:
                enum:
                  - sms
                  - voice
                  - api
                  - sandbox
                  - email
              type: object
            - type: 'null'
          title: Channel Specific Config
        router_config_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Router Config Id
        model_settings:
          anyOf:
            - $ref: '#/components/schemas/ModelChainEntry'
            - type: 'null'
        kb_clearance_level:
          anyOf:
            - type: integer
            - type: 'null'
          title: Kb Clearance Level
        kb_audience_tags:
          items:
            type: string
          type: array
          title: Kb Audience Tags
        created_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - agent_id
        - name
        - created_at
        - updated_at
      title: AgentRevisionResponse
    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
    ContextVarSpec:
      properties:
        name:
          type: string
          title: Name
        type:
          type: string
          enum:
            - string
            - int
            - float
            - bool
            - enum
          title: Type
        source:
          type: string
          enum:
            - system
            - derived
          title: Source
          default: derived
        enum_values:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Enum Values
        reask_cap:
          anyOf:
            - type: integer
            - type: 'null'
          title: Reask Cap
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
      type: object
      required:
        - name
        - type
      title: ContextVarSpec
      description: >-
        Typed definition for a context variable in the compiled graph.


        ``source`` defaults to ``derived`` so ad-hoc fixtures don't need to
        spell

        out the common case; required-ness is per-node
        (``AgentNode.required_writes``),

        not per-variable.


        ``name`` must satisfy the expression-grammar identifier rule
        (``[A-Za-z_]\w*``)

        so that gate/template references can never miss a declared var.
        Read-time loading

        (``list_active_revision_context_variables``) skips+logs any legacy row
        that

        violates this, so old data degrades safely without blocking startup.
    ChannelConfig:
      properties:
        prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt
        first_speaking_config:
          anyOf:
            - $ref: '#/components/schemas/FirstSpeakingConfig'
            - type: 'null'
        warm_transfer:
          anyOf:
            - $ref: '#/components/schemas/WarmTransferChannelConfig'
            - type: 'null'
      type: object
      title: ChannelConfig
      description: |-
        Per-channel agent config addon.

        ``prompt`` is an additive system-prompt addon for this channel
        (templated). ``first_speaking_config`` is the first-speaking config
        for this channel (also templated). ``warm_transfer`` carries the
        voice-channel warm-transfer briefing script. All optional — a channel
        may have any combination.

        Stored as a JSON dict keyed by channel name on
        ``AgentRevision.channel_specific_config``. Future channel-specific
        fields (tools, voice_config) extend this model additively.
    ModelChainEntry:
      properties:
        model:
          type: string
          title: Model
        config:
          $ref: '#/components/schemas/ModelConfig'
      type: object
      required:
        - model
      title: ModelChainEntry
    FirstSpeakingConfig:
      properties:
        first_speaker:
          type: string
          enum:
            - agent
            - user
          title: First Speaker
          default: agent
        mode:
          type: string
          enum:
            - static
            - dynamic
          title: Mode
          default: static
        text:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
          title: Text
        instructions:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
          title: Instructions
        interruptible:
          type: boolean
          title: Interruptible
          default: true
        ai_disclosure_text:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Ai Disclosure Text
      type: object
      title: FirstSpeakingConfig
      description: |-
        Config for the AI's opening turn (no user input yet).

        Lives inside ``ChannelConfig`` — first-speaking is per-channel.

        Mode-agnostic fields:
        - ``first_speaker``: ``"agent"`` opens the call with the rendered
          message; ``"user"`` skips the greeting (caller speaks first).
          Non-voice channels treat the inbound user message as the
          ``"user"`` opener and ignore this field at runtime.

        Greeting source (only applies when ``first_speaker="agent"``):
        - ``static`` mode: ``text`` is required and emitted verbatim
          (templated via the shared ``{{var}}`` engine, ``src.shared.templating.render``).
        - ``dynamic`` mode: ``instructions`` are sent to the model router
          with the agent persona to render an opening line (instructions
          are templated). When omitted/empty, ``instructions`` falls back
          to ``DEFAULT_DYNAMIC_FIRST_SPEAKING_INSTRUCTIONS`` so operators
          who just want a generic friendly opener don't have to author copy.

        Voice-only fields (ignored on non-audio channels):
        - ``interruptible``: whether the caller can barge in mid-greeting.
        - ``ai_disclosure_text``: regulatory disclosure (e.g. CA SB 1001),
          played as an uninterruptible TTS frame BEFORE the greeting.
          Disclosure plays even when ``first_speaker="user"`` because the
          regulation requires the disclosure regardless of who speaks first.
    WarmTransferChannelConfig:
      properties:
        briefing_template:
          anyOf:
            - type: string
              maxLength: 4000
            - type: 'null'
          title: Briefing Template
      type: object
      title: WarmTransferChannelConfig
      description: >-
        Per-revision warm-transfer copy that versions with the agent revision.


        Holds the ``briefing_template`` the SupervisorAgent renders to brief the
        human

        supervisor on the customer's situation (templated via the shared
        ``{{var}}`` engine,

        ``src.shared.templating.render``, against the customer
        transcript/context). Lives under

        ``channel_specific_config["voice"]["warm_transfer"]`` so it clones
        forward with the

        revision like the system prompt. The platform-tool
        ``WarmTransferConfig`` (enabled,

        timeouts, fallback) is the agent-stable infra knob; this is the
        per-revision script.
    ModelConfig:
      properties:
        temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Temperature
        max_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Tokens
        top_p:
          anyOf:
            - type: number
            - type: 'null'
          title: Top P
        stop_sequences:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Stop Sequences
        reasoning_effort:
          anyOf:
            - type: string
              enum:
                - none
                - low
                - medium
                - high
                - xhigh
            - type: 'null'
          title: Reasoning Effort
        request_timeout_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Request Timeout Ms
        thinking_budget:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Thinking Budget
      type: object
      title: ModelConfig
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````