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

# Update agent configuration

> Update the agent configuration identified by {sId} in the workspace identified by {wId}.



## OpenAPI

````yaml /docs/developer-platform/ruby-api-documentation/openapi.json patch /api/v1/w/{wId}/assistant/agent_configurations/{sId}
openapi: 3.0.0
info:
  title: Ruby API
  version: 1.0.2
  description: OpenAPI specification for the Ruby API.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://app.ruby.ad
    description: Ruby API
security: []
tags:
  - name: Users
    description: User management
  - name: Agents
    description: Agent configurations
  - name: Analytics
    description: Workspace analytics
  - name: Apps
    description: Ruby apps
  - name: Conversations
    description: Conversations
  - name: Datasources
    description: Data sources
  - name: DatasourceViews
    description: Data source views
  - name: Feedbacks
    description: Message feedbacks
  - name: MCP
    description: MCP servers
  - name: Mentions
    description: Mentions
  - name: Search
    description: Search
  - name: Skills
    description: Skills
  - name: Spaces
    description: Spaces
  - name: Tools
    description: Tools
  - name: Triggers
    description: Triggers
  - name: Workspace
    description: Workspace
  - name: Private Agents
    description: Private API - Agent configurations
  - name: Private Authentication
    description: Private API - Authentication (WorkOS)
  - name: Private Conversations
    description: Private API - Conversations
  - name: Private Events
    description: Private API - SSE event streams
  - name: Private Extension
    description: Private API - Extension configuration
  - name: Private Files
    description: Private API - File uploads
  - name: Private Mentions
    description: Private API - Mention suggestions
  - name: Private Messages
    description: Private API - Messages
  - name: Private Spaces
    description: Private API - Spaces and data source views
  - name: Private User
    description: Private API - User
  - name: Private Workspace
    description: Private API - Workspace settings
paths:
  /api/v1/w/{wId}/assistant/agent_configurations/{sId}:
    patch:
      tags:
        - Agents
      summary: Update agent configuration
      description: >-
        Update the agent configuration identified by {sId} in the workspace
        identified by {wId}.
      parameters:
        - in: path
          name: wId
          required: true
          description: ID of the workspace
          schema:
            type: string
        - in: path
          name: sId
          required: true
          description: ID of the agent configuration
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userFavorite:
                  type: boolean
                agent:
                  type: object
                  properties:
                    handle:
                      type: string
                    description:
                      type: string
                    scope:
                      type: string
                      enum:
                        - visible
                        - hidden
                    avatar_url:
                      type: string
                    max_steps_per_run:
                      type: number
                    visualization_enabled:
                      type: boolean
                instructions:
                  type: string
                generation_settings:
                  type: object
                  properties:
                    model_id:
                      type: string
                    provider_id:
                      type: string
                    temperature:
                      type: number
                    reasoning_effort:
                      type: string
                tags:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      kind:
                        type: string
                        enum:
                          - standard
                          - protected
                editors:
                  type: array
                  description: >-
                    Emails of the workspace members to set as editors of the
                    agent. Omitting this field keeps the current editors;
                    providing it replaces the whole list.
                  items:
                    type: string
                    format: email
                  example:
                    - alice@example.com
                skills:
                  type: array
                  description: Replaces the skills enabled on the agent configuration.
                  items:
                    type: object
                    required:
                      - sId
                      - name
                    properties:
                      sId:
                        type: string
                      name:
                        type: string
                toolset:
                  type: array
                  description: >-
                    Replaces the full set of tools on the agent. Any tool not
                    present in this array is removed, so send the complete
                    desired toolset. Each entry resolves an MCP server by name
                    (see configuration.mcp_server_name). Entries that cannot be
                    resolved are not applied and are returned in the
                    skippedActions field of the response rather than causing the
                    whole request to fail.
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      description:
                        type: string
                      type:
                        type: string
                        enum:
                          - MCP
                      configuration:
                        type: object
                        properties:
                          mcp_server_name:
                            type: string
                            description: >-
                              Name of the MCP server to attach. Both built-in
                              (internal) tools and remote MCP servers are
                              supported. A remote MCP server must first be
                              shared to a space (global or a regular space the
                              caller can access); it is matched by its display
                              name, which must be unambiguous within the
                              workspace.
      responses:
        '200':
          description: Successfully updated agent configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  agentConfiguration:
                    $ref: '#/components/schemas/AgentConfiguration'
                  skippedActions:
                    type: array
                    description: >-
                      Toolset entries that could not be applied (e.g. the
                      referenced MCP server was not found, is not shared to an
                      accessible space, or the name was ambiguous). The request
                      still succeeds; inspect this list to confirm every
                      intended tool was attached.
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        reason:
                          type: string
        '400':
          description: Bad Request. Invalid or missing parameters.
        '401':
          description: Unauthorized. Invalid or missing authentication token.
        '403':
          description: Forbidden. Only admins can update agents.
        '404':
          description: Agent configuration not found.
        '500':
          description: Internal Server Error.
      security:
        - BearerAuth: []
components:
  schemas:
    AgentConfiguration:
      type: object
      properties:
        id:
          type: integer
          example: 12345
        agentModelId:
          type: integer
          nullable: true
          description: >-
            Stable identifier of the agent across versions; null for global
            agents
          example: 6789
        sId:
          type: string
          description: Unique string identifier for the agent configuration
          example: 7f3a9c2b1e
        version:
          type: integer
          example: 2
        versionCreatedAt:
          type: string
          nullable: true
          description: Timestamp of when the version was created
          example: '2023-06-15T14:30:00Z'
        versionAuthorId:
          type: string
          nullable: true
          description: ID of the user who created this version
          example: 0ec9852c2f
        name:
          type: string
          description: Name of the agent configuration
          example: Customer Support Agent
        description:
          type: string
          description: Description of the agent configuration
          example: An AI agent designed to handle customer support inquiries
        instructions:
          type: string
          nullable: true
          description: Instructions for the agent
          example: >-
            Always greet the customer politely and try to resolve their issue
            efficiently.
        pictureUrl:
          type: string
          description: URL of the agent's picture
          example: https://example.com/agent-images/support-agent.png
        status:
          type: string
          description: Current status of the agent configuration
          example: active
        scope:
          type: string
          description: Scope of the agent configuration
          example: workspace
        userFavorite:
          type: boolean
          description: Status of the user favorite for this configuration
          example: true
        model:
          type: object
          properties:
            providerId:
              type: string
              description: ID of the model provider
              example: openai
            modelId:
              type: string
              description: ID of the specific model
              example: gpt-4
            temperature:
              type: number
              example: 0.7
        actions:
          type: array
          example: []
        skills:
          type: array
          description: >-
            Skills attached to the agent. Returned by the agent GET endpoints
            (list and single-agent) whatever the requested variant. Empty both
            for an agent with no skill and for an agent whose details were
            redacted for the caller (canRead false).
          items:
            $ref: '#/components/schemas/AgentSkill'
        tags:
          type: array
          description: Tags attached to the agent
          items:
            type: object
            properties:
              sId:
                type: string
                example: 3f9d1c7a5b
              name:
                type: string
                example: Support
              kind:
                type: string
                enum:
                  - standard
                  - protected
        requestedSpaceIds:
          type: array
          description: Identifiers of the spaces the agent needs access to
          items:
            type: string
          example:
            - vlt_a1b2c3d4e5
        maxStepsPerRun:
          type: integer
          example: 10
        templateId:
          type: string
          nullable: true
          description: ID of the template used for this configuration
          example: b4e2f1a9c7
    AgentSkill:
      type: object
      description: A skill attached to an agent configuration.
      properties:
        sId:
          type: string
          description: Unique string identifier for the skill
          example: skill_abc123
        name:
          type: string
          description: Name of the skill
          example: Customer Support
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Your RUBY API key is a Bearer token.

````

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