> ## Documentation Index
> Fetch the complete documentation index at: https://oma-codex-339-workspace-permissions.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Agent

> Update Agent through the OMA API.

<Info>Every request requires `?beta=true`.</Info>


## OpenAPI

````yaml /openapi/oma.en.json post /v1/agents/{agent_id}
openapi: 3.1.0
info:
  title: OMA API Reference
  version: 1.0.0
  description: Open Managed Agents application API reference.
servers:
  - url: http://localhost:38080
    description: Local OMA server
security:
  - omaApiKey: []
  - omaBearer: []
paths:
  /v1/agents/{agent_id}:
    post:
      summary: Update Agent
      operationId: BetaUpdateAgent
      parameters:
        - name: beta
          in: query
          required: true
          description: Selects the beta API contract for this endpoint. Must be `true`.
          schema:
            type: boolean
            enum:
              - true
            x-default: true
        - name: anthropic-version
          in: header
          required: false
          schema:
            type: string
            x-default: '2023-06-01'
          description: The OMA API compatibility version to use.
        - name: anthropic-beta
          in: header
          required: false
          schema:
            type: string
            items:
              type: string
            x-stainless-override-schema:
              x-stainless-param: betas
              x-stainless-extend-default: true
              type: array
              description: Optional header to specify the beta version(s) you want to use.
              items:
                $ref: '#/components/schemas/AnthropicBeta'
            x-default: managed-agents-2026-04-01
          description: Beta header that enables the Managed Agents API contract.
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            x-stainless-cli-data-alias: id
          description: Path parameter agent_id
          example: agent_011CZkYpogX7uDKUyvBTophP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BetaManagedAgentsUpdateAgentParams'
            example:
              description: updated
      responses:
        '200':
          description: Successful response (OK)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsAgent'
        '400':
          description: Invalid argument - The client specified an invalid argument
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '401':
          description: >-
            Unauthenticated - The request does not have valid authentication
            credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '403':
          description: >-
            Permission denied - The caller does not have permission to execute
            the specified operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '404':
          description: Not found - Some requested entity was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '408':
          description: >-
            Deadline exceeded - The deadline expired before the operation could
            complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '409':
          description: Aborted - The operation was aborted due to concurrency issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '412':
          description: >-
            Failed precondition - Operation was rejected because the system is
            not in required state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '413':
          description: Out of range - Operation was attempted past the valid range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '429':
          description: >-
            Resource exhausted - Some resource has been exhausted (rate
            limiting)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '431':
          description: Request header fields too large - Request metadata was too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '499':
          description: Cancelled - The operation was cancelled by the client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '500':
          description: Internal - Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '501':
          description: Unimplemented - The operation is not implemented or supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '503':
          description: Unavailable - The service is currently unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '504':
          description: Deadline exceeded - Upstream service did not respond in time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
components:
  schemas:
    BetaManagedAgentsUpdateAgentParams:
      description: >-
        Request parameters for updating an `agent`. Omit a field to preserve its
        current value.
      type: object
      additionalProperties: false
      properties:
        version:
          description: >-
            The agent's current version, used to prevent concurrent overwrites.
            Obtain this value from a create or retrieve response. Must be at
            least 1 if specified. When supplied, the request fails if it does
            not match the server's current version; omit to apply the update
            unconditionally.
          type: integer
          format: int32
          examples:
            - 1
        name:
          description: >-
            Human-readable name. Must be non-empty. Omit to preserve. Cannot be
            cleared.
          type: string
          maxLength: 256
        description:
          description: Description. Omit to preserve; send empty string or null to clear.
          type: string
          maxLength: 2048
          nullable: true
        model:
          description: >-
            Model identifier. Accepts the model string, e.g. `claude-opus-4-6`,
            or a `model_config` object for additional configuration control.
            Omit to preserve. Cannot be cleared.
          allOf:
            - $ref: '#/components/schemas/BetaManagedAgentsModelParams'
        system:
          description: System prompt. Omit to preserve; send empty string or null to clear.
          type: string
          maxLength: 100000
          nullable: true
          examples:
            - >-
              You are a general-purpose agent that can research, write code, run
              commands, and use connected tools to complete the user's task end
              to end.
        tools:
          description: >-
            Tool configurations available to the agent. Full replacement. Omit
            to preserve; send empty array or null to clear. Maximum of 128 tools
            across all toolsets allowed.
          type: array
          items:
            $ref: '#/components/schemas/BetaManagedAgentsAgentToolParams'
          nullable: true
        mcp_servers:
          description: >-
            MCP servers. Full replacement. Omit to preserve; send empty array or
            `null` to clear. Names must be unique. Maximum 20. Every server must
            be referenced by an `mcp_toolset` in the agent's resulting `tools`;
            unreferenced servers are rejected. See the MCP connector guide.
          type: array
          items:
            $ref: '#/components/schemas/BetaManagedAgentsMCPServerParams'
          nullable: true
        skills:
          description: >-
            Skills. Full replacement. Omit to preserve; send empty array or null
            to clear.
          type: array
          items:
            $ref: '#/components/schemas/BetaManagedAgentsSkillParams'
          nullable: true
        metadata:
          description: >-
            Metadata patch. Set a key to a string to upsert it, or to null to
            delete it. Omit the field to preserve. The stored bag is limited to
            16 keys (up to 64 chars each) with values up to 512 chars.
          type: object
          additionalProperties:
            type: string
            nullable: true
          nullable: true
        multiagent:
          description: >-
            Multiagent orchestration configuration. Full replacement. Omit to
            preserve; send null to clear.
          allOf:
            - $ref: '#/components/schemas/BetaManagedAgentsMultiagentParams'
          nullable: true
      example:
        version: 1
        system: >-
          You are a general-purpose agent that can research, write code, run
          commands, and use connected tools to complete the user's task end to
          end.
    BetaManagedAgentsAgent:
      description: A Managed Agents `agent`.
      type: object
      additionalProperties: false
      required:
        - id
        - archived_at
        - created_at
        - description
        - mcp_servers
        - metadata
        - model
        - multiagent
        - name
        - skills
        - system
        - tools
        - type
        - updated_at
        - version
      properties:
        id:
          type: string
          examples:
            - agent_011CZkYpogX7uDKUyvBTophP
        archived_at:
          description: When the agent was archived. Null if not archived.
          allOf:
            - $ref: '#/components/schemas/BetaTimestamp'
          nullable: true
          examples:
            - null
        created_at:
          $ref: '#/components/schemas/BetaTimestamp'
          examples:
            - '2026-03-15T10:00:00Z'
        description:
          type: string
          nullable: true
          examples:
            - A general-purpose starter agent.
        mcp_servers:
          type: array
          items:
            $ref: '#/components/schemas/BetaManagedAgentsMCPServer'
          examples:
            - - type: url
                name: example-mcp
                url: https://example-server.modelcontextprotocol.io/sse
        metadata:
          type: object
          additionalProperties:
            type: string
          examples:
            - foo: bar
        model:
          $ref: '#/components/schemas/BetaManagedAgentsModelConfig'
          examples:
            - id: claude-sonnet-4-6
              effort:
                type: low
              inference_geo: inference_geo
              speed: standard
        multiagent:
          description: >-
            Multiagent orchestration configuration. Null when the agent is
            single-threaded.
          allOf:
            - $ref: '#/components/schemas/BetaManagedAgentsMultiagent'
          nullable: true
          examples:
            - agents:
                - id: agent_011CZkYqphY8vELVzwCUpqiQ
                  type: agent
                  version: 1
              type: coordinator
        name:
          type: string
          examples:
            - My First Agent
        skills:
          type: array
          items:
            $ref: '#/components/schemas/BetaManagedAgentsSkill'
          examples:
            - - type: anthropic
                skill_id: xlsx
                version: '1'
              - type: custom
                skill_id: skill_011CZkZFNu9hAbo3jZPRgTlx
                version: '2'
        system:
          type: string
          nullable: true
          examples:
            - >-
              You are a general-purpose agent that can research, write code, run
              commands, and use connected tools to complete the user's task end
              to end.
        tools:
          type: array
          items:
            $ref: '#/components/schemas/BetaManagedAgentsAgentTool'
          examples:
            - - configs:
                  - enabled: true
                    name: bash
                    permission_policy:
                      type: always_allow
                default_config:
                  enabled: true
                  permission_policy:
                    type: always_ask
                type: agent_toolset_20260401
        type:
          type: string
          enum:
            - agent
          examples:
            - agent
        updated_at:
          $ref: '#/components/schemas/BetaTimestamp'
          examples:
            - '2026-03-15T10:00:00Z'
        version:
          description: >-
            The agent's current version. Starts at 1 and increments when the
            agent is modified.
          type: integer
          format: int32
          examples:
            - 1
      example:
        id: agent_011CZkYpogX7uDKUyvBTophP
        archived_at: null
        created_at: '2026-03-15T10:00:00Z'
        description: A general-purpose starter agent.
        mcp_servers:
          - name: example-mcp
            type: url
            url: https://example-server.modelcontextprotocol.io/sse
        metadata:
          foo: bar
        model:
          id: claude-sonnet-4-6
          effort:
            type: low
          inference_geo: inference_geo
          speed: standard
        multiagent:
          agents:
            - id: agent_011CZkYqphY8vELVzwCUpqiQ
              type: agent
              version: 1
          type: coordinator
        name: My First Agent
        skills:
          - skill_id: xlsx
            type: anthropic
            version: '1'
          - skill_id: skill_011CZkZFNu9hAbo3jZPRgTlx
            type: custom
            version: '2'
        system: >-
          You are a general-purpose agent that can research, write code, run
          commands, and use connected tools to complete the user's task end to
          end.
        tools:
          - configs:
              - enabled: true
                name: bash
                permission_policy:
                  type: always_allow
            default_config:
              enabled: true
              permission_policy:
                type: always_ask
            type: agent_toolset_20260401
        type: agent
        updated_at: '2026-03-15T10:00:00Z'
        version: 1
    BetaErrorResponse:
      properties:
        error:
          discriminator:
            mapping:
              api_error:
                $ref: '#/components/schemas/BetaAPIError'
              authentication_error:
                $ref: '#/components/schemas/BetaAuthenticationError'
              billing_error:
                $ref: '#/components/schemas/BetaBillingError'
              invalid_request_error:
                $ref: '#/components/schemas/BetaInvalidRequestError'
              not_found_error:
                $ref: '#/components/schemas/BetaNotFoundError'
              overloaded_error:
                $ref: '#/components/schemas/BetaOverloadedError'
              permission_error:
                $ref: '#/components/schemas/BetaPermissionError'
              rate_limit_error:
                $ref: '#/components/schemas/BetaRateLimitError'
              timeout_error:
                $ref: '#/components/schemas/BetaGatewayTimeoutError'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/BetaInvalidRequestError'
            - $ref: '#/components/schemas/BetaAuthenticationError'
            - $ref: '#/components/schemas/BetaBillingError'
            - $ref: '#/components/schemas/BetaPermissionError'
            - $ref: '#/components/schemas/BetaNotFoundError'
            - $ref: '#/components/schemas/BetaRateLimitError'
            - $ref: '#/components/schemas/BetaGatewayTimeoutError'
            - $ref: '#/components/schemas/BetaAPIError'
            - $ref: '#/components/schemas/BetaOverloadedError'
          title: Error
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Request Id
        type:
          const: error
          default: error
          title: Type
          type: string
      required:
        - error
        - request_id
        - type
      title: ErrorResponse
      type: object
    BetaManagedAgentsModelParams:
      oneOf:
        - title: BetaManagedAgentsModel
          allOf:
            - $ref: '#/components/schemas/BetaManagedAgentsModel'
          x-stainless-skip:
            - go
            - cli
        - $ref: '#/components/schemas/BetaManagedAgentsModelConfigParams'
    BetaManagedAgentsAgentToolParams:
      description: Union type for tool configurations in the tools array.
      type: object
      discriminator:
        propertyName: type
        mapping:
          agent_toolset_20260401:
            $ref: '#/components/schemas/BetaManagedAgentsAgentToolset20260401Params'
          mcp_toolset:
            $ref: '#/components/schemas/BetaManagedAgentsMCPToolsetParams'
          custom:
            $ref: '#/components/schemas/BetaManagedAgentsCustomToolParams'
      oneOf:
        - $ref: '#/components/schemas/BetaManagedAgentsAgentToolset20260401Params'
        - $ref: '#/components/schemas/BetaManagedAgentsMCPToolsetParams'
        - $ref: '#/components/schemas/BetaManagedAgentsCustomToolParams'
    BetaManagedAgentsMCPServerParams:
      description: Union type for MCP server connection definitions.
      type: object
      discriminator:
        propertyName: type
        mapping:
          url:
            $ref: '#/components/schemas/BetaManagedAgentsURLMCPServerParams'
      oneOf:
        - $ref: '#/components/schemas/BetaManagedAgentsURLMCPServerParams'
    BetaManagedAgentsSkillParams:
      description: Skill to load in the session container.
      discriminator:
        propertyName: type
        mapping:
          anthropic:
            $ref: '#/components/schemas/BetaManagedAgentsAnthropicSkillParams'
          custom:
            $ref: '#/components/schemas/BetaManagedAgentsCustomSkillParams'
      oneOf:
        - $ref: '#/components/schemas/BetaManagedAgentsAnthropicSkillParams'
        - $ref: '#/components/schemas/BetaManagedAgentsCustomSkillParams'
    BetaManagedAgentsMultiagentParams:
      description: >-
        Multiagent orchestration configuration. Currently supports the
        `coordinator` topology.
      discriminator:
        propertyName: type
        mapping:
          coordinator:
            $ref: '#/components/schemas/BetaManagedAgentsMultiagentCoordinatorParams'
      oneOf:
        - $ref: '#/components/schemas/BetaManagedAgentsMultiagentCoordinatorParams'
    BetaTimestamp:
      description: A timestamp in RFC 3339 format
      type: string
      format: date-time
    BetaManagedAgentsMCPServer:
      description: >-
        Union type for MCP server connection definitions returned in API
        responses.
      type: object
      discriminator:
        propertyName: type
        mapping:
          url:
            $ref: '#/components/schemas/BetaManagedAgentsMCPServerURLDefinition'
      oneOf:
        - $ref: '#/components/schemas/BetaManagedAgentsMCPServerURLDefinition'
    BetaManagedAgentsModelConfig:
      description: Model identifier and configuration.
      type: object
      additionalProperties: false
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/BetaManagedAgentsModel'
        effort:
          description: >-
            How hard the model works on each inference call. One of `low`,
            `medium`, `high`, `xhigh`, `max`. Always present; resolved to the
            per-model default at save time when not supplied.
          allOf:
            - $ref: '#/components/schemas/BetaManagedAgentsEffort'
          examples:
            - type: low
        inference_geo:
          description: >-
            Geographic region for model inference. When unset, requests fall
            through to the workspace's default_inference_geo.
          type: string
          examples:
            - inference_geo
        speed:
          description: >-
            Inference speed mode. `fast` provides significantly faster output
            token generation at premium pricing. Defaults to `standard`. Not all
            models support `fast`; invalid combinations are rejected at create
            time.
          allOf:
            - $ref: '#/components/schemas/BetaManagedAgentsSpeed'
          examples:
            - standard
      example:
        id: claude-sonnet-4-6
        effort:
          type: low
        inference_geo: inference_geo
        speed: standard
    BetaManagedAgentsMultiagent:
      description: >-
        Resolved multiagent orchestration configuration as returned in API
        responses.
      discriminator:
        propertyName: type
        mapping:
          coordinator:
            $ref: '#/components/schemas/BetaManagedAgentsMultiagentCoordinator'
      oneOf:
        - $ref: '#/components/schemas/BetaManagedAgentsMultiagentCoordinator'
    BetaManagedAgentsSkill:
      description: Resolved skill as returned in API responses.
      discriminator:
        propertyName: type
        mapping:
          anthropic:
            $ref: '#/components/schemas/BetaManagedAgentsAnthropicSkill'
          custom:
            $ref: '#/components/schemas/BetaManagedAgentsCustomSkill'
      oneOf:
        - $ref: '#/components/schemas/BetaManagedAgentsAnthropicSkill'
        - $ref: '#/components/schemas/BetaManagedAgentsCustomSkill'
    BetaManagedAgentsAgentTool:
      description: Union type for tool configurations returned in API responses.
      type: object
      discriminator:
        propertyName: type
        mapping:
          agent_toolset_20260401:
            $ref: '#/components/schemas/BetaManagedAgentsAgentToolset20260401'
          mcp_toolset:
            $ref: '#/components/schemas/BetaManagedAgentsMCPToolset'
          custom:
            $ref: '#/components/schemas/BetaManagedAgentsCustomTool'
      oneOf:
        - $ref: '#/components/schemas/BetaManagedAgentsAgentToolset20260401'
        - $ref: '#/components/schemas/BetaManagedAgentsMCPToolset'
        - $ref: '#/components/schemas/BetaManagedAgentsCustomTool'
    BetaAPIError:
      properties:
        message:
          default: Internal server error
          title: Message
          type: string
        type:
          const: api_error
          default: api_error
          title: Type
          type: string
      required:
        - message
        - type
      title: APIError
      type: object
    BetaAuthenticationError:
      properties:
        message:
          default: Authentication error
          title: Message
          type: string
        type:
          const: authentication_error
          default: authentication_error
          title: Type
          type: string
      required:
        - message
        - type
      title: AuthenticationError
      type: object
    BetaBillingError:
      properties:
        message:
          default: Billing error
          title: Message
          type: string
        type:
          const: billing_error
          default: billing_error
          title: Type
          type: string
      required:
        - message
        - type
      title: BillingError
      type: object
    BetaInvalidRequestError:
      properties:
        message:
          default: Invalid request
          title: Message
          type: string
        type:
          const: invalid_request_error
          default: invalid_request_error
          title: Type
          type: string
      required:
        - message
        - type
      title: InvalidRequestError
      type: object
    BetaNotFoundError:
      properties:
        message:
          default: Not found
          title: Message
          type: string
        type:
          const: not_found_error
          default: not_found_error
          title: Type
          type: string
      required:
        - message
        - type
      title: NotFoundError
      type: object
    BetaOverloadedError:
      properties:
        message:
          default: Overloaded
          title: Message
          type: string
        type:
          const: overloaded_error
          default: overloaded_error
          title: Type
          type: string
      required:
        - message
        - type
      title: OverloadedError
      type: object
    BetaPermissionError:
      properties:
        message:
          default: Permission denied
          title: Message
          type: string
        type:
          const: permission_error
          default: permission_error
          title: Type
          type: string
      required:
        - message
        - type
      title: PermissionError
      type: object
    BetaRateLimitError:
      properties:
        message:
          default: Rate limited
          title: Message
          type: string
        type:
          const: rate_limit_error
          default: rate_limit_error
          title: Type
          type: string
      required:
        - message
        - type
      title: RateLimitError
      type: object
    BetaGatewayTimeoutError:
      properties:
        message:
          default: Request timeout
          title: Message
          type: string
        type:
          const: timeout_error
          default: timeout_error
          title: Type
          type: string
      required:
        - message
        - type
      title: GatewayTimeoutError
      type: object
    BetaManagedAgentsModel:
      title: BetaManagedAgentsModel
      description: |-
        The model that will power your agent.

        See models for additional details and options.
      anyOf:
        - type: string
        - const: claude-sonnet-5
          description: High-performance model for coding and agents
          x-stainless-nominal: false
        - const: claude-fable-5
          description: >-
            Next generation of intelligence for the hardest knowledge work and
            coding problems
          x-stainless-nominal: false
        - const: claude-opus-5
          description: Powerful intelligence for long-running agents and coding
          x-stainless-nominal: false
        - const: claude-opus-4-8
          description: Powerful intelligence for long-running agents and coding
          x-stainless-nominal: false
        - const: claude-opus-4-7
          description: Powerful intelligence for long-running agents and coding
          x-stainless-nominal: false
        - const: claude-opus-4-6
          description: Powerful intelligence for long-running agents and coding
          x-stainless-nominal: false
        - const: claude-sonnet-4-6
          description: Best combination of speed and intelligence
          x-stainless-nominal: false
        - const: claude-haiku-4-5
          description: Fastest model with near-frontier intelligence
          x-stainless-nominal: false
        - const: claude-haiku-4-5-20251001
          description: Fastest model with near-frontier intelligence
          x-stainless-nominal: false
        - const: claude-opus-4-5
          description: Powerful intelligence for long-running agents and coding
          x-stainless-nominal: false
        - const: claude-opus-4-5-20251101
          description: Powerful intelligence for long-running agents and coding
          x-stainless-nominal: false
        - const: claude-sonnet-4-5
          description: High-performance model for agents and coding
          x-stainless-nominal: false
        - const: claude-sonnet-4-5-20250929
          description: High-performance model for agents and coding
          x-stainless-nominal: false
    BetaManagedAgentsModelConfigParams:
      description: An object that defines additional configuration control over model use
      type: object
      additionalProperties: false
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/BetaManagedAgentsModel'
        effort:
          description: >-
            How hard the model works on each inference call. Accepts a bare
            level string (`"high"`) or `{"type": "high"}`. On create, omitting
            it resolves the per-model default; on update, omitting it leaves the
            stored value unchanged.
          allOf:
            - $ref: '#/components/schemas/BetaManagedAgentsEffortParams'
          nullable: true
        inference_geo:
          description: >-
            Geographic region for model inference. When unset, requests fall
            through to the workspace's default_inference_geo. On update, `model`
            is whole-object replacement — omitting inference_geo clears it.
          type: string
          nullable: true
        speed:
          description: Inference speed mode. Defaults to `standard`.
          allOf:
            - $ref: '#/components/schemas/BetaManagedAgentsSpeed'
          nullable: true
      example:
        id: claude-opus-4-8
    BetaManagedAgentsAgentToolset20260401Params:
      description: >-
        Configuration for built-in agent tools. Use this to enable or disable
        groups of tools available to the agent.
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - agent_toolset_20260401
        configs:
          description: Per-tool configuration overrides.
          type: array
          items:
            $ref: '#/components/schemas/BetaManagedAgentsAgentToolConfigParams'
        default_config:
          description: Default configuration applied to all tools in this set.
          allOf:
            - $ref: >-
                #/components/schemas/BetaManagedAgentsAgentToolsetDefaultConfigParams
          nullable: true
    BetaManagedAgentsMCPToolsetParams:
      description: Configuration for tools from an MCP server defined in `mcp_servers`.
      type: object
      additionalProperties: false
      required:
        - mcp_server_name
        - type
      properties:
        mcp_server_name:
          description: >-
            Name of the MCP server. Must match a server name from the
            mcp_servers array. 1-255 characters.
          type: string
          minLength: 1
          maxLength: 255
        type:
          type: string
          enum:
            - mcp_toolset
        configs:
          description: Per-tool configuration overrides.
          type: array
          items:
            $ref: '#/components/schemas/BetaManagedAgentsMCPToolConfigParams'
        default_config:
          description: Default configuration for all tools from this server.
          allOf:
            - $ref: >-
                #/components/schemas/BetaManagedAgentsMCPToolsetDefaultConfigParams
          nullable: true
    BetaManagedAgentsCustomToolParams:
      description: >-
        A custom tool that is executed by the API client rather than the agent.
        When the agent calls this tool, an `agent.custom_tool_use` event is
        emitted and the session goes idle, waiting for the client to provide the
        result via a `user.custom_tool_result` event.
      type: object
      additionalProperties: false
      required:
        - description
        - input_schema
        - name
        - type
      properties:
        description:
          description: >-
            Description of what the tool does, shown to the agent to help it
            decide when to use the tool.
          type: string
          minLength: 1
        input_schema:
          description: JSON Schema defining the expected input parameters for the tool.
          allOf:
            - $ref: '#/components/schemas/BetaManagedAgentsCustomToolInputSchema'
        name:
          description: >-
            Unique name for the tool. 1-128 characters; letters, digits,
            underscores, and hyphens.
          type: string
          minLength: 1
          maxLength: 128
        type:
          type: string
          enum:
            - custom
    BetaManagedAgentsURLMCPServerParams:
      description: URL-based MCP server connection.
      type: object
      additionalProperties: false
      required:
        - name
        - type
        - url
      properties:
        name:
          description: >-
            Unique name for this server, referenced by mcp_toolset
            configurations. 1-255 characters.
          type: string
          minLength: 1
          maxLength: 255
          examples:
            - example-mcp
        type:
          type: string
          enum:
            - url
          examples:
            - url
        url:
          description: Endpoint URL for the MCP server.
          type: string
          maxLength: 2048
          examples:
            - https://example-server.modelcontextprotocol.io/sse
      example:
        type: url
        name: example-mcp
        url: https://example-server.modelcontextprotocol.io/sse
    BetaManagedAgentsAnthropicSkillParams:
      description: An OMA-managed skill.
      type: object
      additionalProperties: false
      required:
        - skill_id
        - type
      properties:
        skill_id:
          description: Identifier of the OMA skill (e.g., "xlsx").
          type: string
          minLength: 1
          maxLength: 64
          examples:
            - xlsx
        type:
          type: string
          enum:
            - anthropic
          examples:
            - anthropic
        version:
          description: Version to pin. Defaults to latest if omitted.
          type: string
          minLength: 1
          maxLength: 64
          nullable: true
          examples:
            - '1'
      example:
        type: anthropic
        skill_id: xlsx
        version: '1'
    BetaManagedAgentsCustomSkillParams:
      description: A user-created custom skill.
      type: object
      additionalProperties: false
      required:
        - skill_id
        - type
      properties:
        skill_id:
          description: Tagged ID of the custom skill (e.g., "skill_01XJ5...").
          type: string
          minLength: 1
          maxLength: 64
          examples:
            - skill_011CZkZFNu9hAbo3jZPRgTlx
        type:
          type: string
          enum:
            - custom
          examples:
            - custom
        version:
          description: Version to pin. Defaults to latest if omitted.
          type: string
          minLength: 1
          maxLength: 64
          nullable: true
          examples:
            - '2'
      example:
        type: custom
        skill_id: skill_011CZkZFNu9hAbo3jZPRgTlx
        version: '2'
    BetaManagedAgentsMultiagentCoordinatorParams:
      description: >-
        A coordinator topology: the session's primary thread orchestrates work
        by spawning session threads, each running an agent drawn from the
        `agents` roster.
      type: object
      additionalProperties: false
      required:
        - agents
        - type
      properties:
        agents:
          description: >-
            Agents the coordinator may spawn as session threads. 1–20 entries.
            Each entry is an agent ID string, a versioned
            `{"type":"agent","id","version"}` reference, or `{"type":"self"}` to
            allow recursive self-invocation. Entries must reference distinct
            agents (after resolving `self` and string forms); at most one
            `self`. Referenced agents must exist, must not be archived, and must
            not themselves have `multiagent` set (depth limit 1).
          type: array
          items:
            $ref: '#/components/schemas/BetaManagedAgentsMultiagentRosterEntryParams'
          examples:
            - - agent_011CZkYqphY8vELVzwCUpqiQ
              - type: self
        type:
          type: string
          enum:
            - coordinator
          examples:
            - coordinator
      example:
        type: coordinator
        agents:
          - agent_011CZkYqphY8vELVzwCUpqiQ
          - type: self
    BetaManagedAgentsMCPServerURLDefinition:
      description: URL-based MCP server connection as returned in API responses.
      type: object
      additionalProperties: false
      required:
        - name
        - type
        - url
      properties:
        name:
          type: string
          examples:
            - example-mcp
        type:
          type: string
          enum:
            - url
          examples:
            - url
        url:
          type: string
          examples:
            - https://example-server.modelcontextprotocol.io/sse
      example:
        type: url
        name: example-mcp
        url: https://example-server.modelcontextprotocol.io/sse
    BetaManagedAgentsEffort:
      description: >-
        How hard the model works on each turn. Sets `output_config.effort` on
        every Messages call the session makes.
      type: object
      discriminator:
        propertyName: type
        mapping:
          low:
            $ref: '#/components/schemas/BetaManagedAgentsEffortLow'
          medium:
            $ref: '#/components/schemas/BetaManagedAgentsEffortMedium'
          high:
            $ref: '#/components/schemas/BetaManagedAgentsEffortHigh'
          xhigh:
            $ref: '#/components/schemas/BetaManagedAgentsEffortXhigh'
          max:
            $ref: '#/components/schemas/BetaManagedAgentsEffortMax'
      oneOf:
        - $ref: '#/components/schemas/BetaManagedAgentsEffortLow'
        - $ref: '#/components/schemas/BetaManagedAgentsEffortMedium'
        - $ref: '#/components/schemas/BetaManagedAgentsEffortHigh'
        - $ref: '#/components/schemas/BetaManagedAgentsEffortXhigh'
        - $ref: '#/components/schemas/BetaManagedAgentsEffortMax'
    BetaManagedAgentsSpeed:
      type: string
      description: >-
        Inference speed mode. `fast` provides significantly faster output token
        generation at premium pricing. Not all models support `fast`; invalid
        combinations are rejected at create time.
      enum:
        - standard
        - fast
    BetaManagedAgentsMultiagentCoordinator:
      description: Resolved coordinator topology with a concrete agent roster.
      type: object
      additionalProperties: false
      required:
        - agents
        - type
      properties:
        agents:
          description: >-
            Agents the coordinator may spawn as session threads, each resolved
            to a specific version.
          type: array
          items:
            $ref: '#/components/schemas/BetaManagedAgentsMultiagentRosterEntry'
        type:
          type: string
          enum:
            - coordinator
    BetaManagedAgentsAnthropicSkill:
      description: A resolved OMA-managed skill.
      type: object
      additionalProperties: false
      required:
        - skill_id
        - type
        - version
      properties:
        skill_id:
          type: string
          examples:
            - xlsx
        type:
          type: string
          enum:
            - anthropic
          examples:
            - anthropic
        version:
          type: string
          examples:
            - '1'
      example:
        type: anthropic
        skill_id: xlsx
        version: '1'
    BetaManagedAgentsCustomSkill:
      description: A resolved user-created custom skill.
      type: object
      additionalProperties: false
      required:
        - skill_id
        - type
        - version
      properties:
        skill_id:
          type: string
          examples:
            - skill_011CZkZFNu9hAbo3jZPRgTlx
        type:
          type: string
          enum:
            - custom
          examples:
            - custom
        version:
          type: string
          examples:
            - '2'
      example:
        type: custom
        skill_id: skill_011CZkZFNu9hAbo3jZPRgTlx
        version: '2'
    BetaManagedAgentsAgentToolset20260401:
      type: object
      additionalProperties: false
      required:
        - configs
        - default_config
        - type
      properties:
        configs:
          type: array
          items:
            $ref: '#/components/schemas/BetaManagedAgentsAgentToolConfig'
        default_config:
          $ref: '#/components/schemas/BetaManagedAgentsAgentToolsetDefaultConfig'
        type:
          type: string
          enum:
            - agent_toolset_20260401
    BetaManagedAgentsMCPToolset:
      type: object
      additionalProperties: false
      required:
        - configs
        - default_config
        - mcp_server_name
        - type
      properties:
        configs:
          type: array
          items:
            $ref: '#/components/schemas/BetaManagedAgentsMCPToolConfig'
        default_config:
          $ref: '#/components/schemas/BetaManagedAgentsMCPToolsetDefaultConfig'
        mcp_server_name:
          type: string
        type:
          type: string
          enum:
            - mcp_toolset
    BetaManagedAgentsCustomTool:
      description: A custom tool as returned in API responses.
      type: object
      additionalProperties: false
      required:
        - description
        - input_schema
        - name
        - type
      properties:
        description:
          type: string
        input_schema:
          $ref: '#/components/schemas/BetaManagedAgentsCustomToolInputSchema'
        name:
          type: string
        type:
          type: string
          enum:
            - custom
    BetaManagedAgentsEffortParams:
      oneOf:
        - $ref: '#/components/schemas/BetaManagedAgentsEffortLevel'
        - $ref: '#/components/schemas/BetaManagedAgentsEffort'
    BetaManagedAgentsAgentToolConfigParams:
      description: Configuration override for a specific tool within a toolset.
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          $ref: '#/components/schemas/BetaManagedAgentsAgentToolName'
        enabled:
          description: >-
            Whether this tool is enabled and available to the model. Overrides
            the default_config setting.
          type: boolean
          nullable: true
        permission_policy:
          description: >-
            Permission policy for this tool. Controls whether tool calls are
            auto-approved or require confirmation.
          allOf:
            - $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy'
          nullable: true
    BetaManagedAgentsAgentToolsetDefaultConfigParams:
      description: Default configuration for all tools in a toolset.
      type: object
      additionalProperties: false
      properties:
        enabled:
          description: >-
            Whether tools are enabled and available to the model by default.
            Defaults to true if not specified.
          type: boolean
          nullable: true
        permission_policy:
          description: >-
            Default permission policy for tools. Controls whether tool calls are
            auto-approved or require confirmation.
          allOf:
            - $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy'
          nullable: true
    BetaManagedAgentsMCPToolConfigParams:
      description: Configuration override for a specific MCP tool.
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          description: Name of the MCP tool to configure. 1-128 characters.
          type: string
          minLength: 1
          maxLength: 128
        enabled:
          description: >-
            Whether this tool is enabled. Overrides the `default_config`
            setting.
          type: boolean
          nullable: true
        permission_policy:
          description: >-
            Permission policy for this tool. Overrides the `default_config`
            setting.
          allOf:
            - $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy'
          nullable: true
    BetaManagedAgentsMCPToolsetDefaultConfigParams:
      description: Default configuration for all tools from an MCP server.
      type: object
      additionalProperties: false
      properties:
        enabled:
          description: >-
            Whether tools are enabled by default. Defaults to true if not
            specified.
          type: boolean
          nullable: true
        permission_policy:
          description: Default permission policy for tools from this server.
          allOf:
            - $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy'
          nullable: true
    BetaManagedAgentsCustomToolInputSchema:
      additionalProperties: true
      description: JSON Schema for custom tool input parameters.
      properties:
        type:
          const: object
          title: Type
          type: string
        properties:
          anyOf:
            - type: object
              additionalProperties: true
            - type: 'null'
          title: Properties
          x-stainless-skip:
            - terraform
        required:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Required
      required:
        - type
      type: object
    BetaManagedAgentsMultiagentRosterEntryParams:
      description: >-
        An entry in a multiagent roster: an agent ID string, a versioned agent
        reference, or `self`.
      oneOf:
        - type: string
        - oneOf:
            - $ref: '#/components/schemas/BetaManagedAgentsAgentParams'
            - $ref: '#/components/schemas/BetaManagedAgentsMultiagentSelfParams'
            - $ref: '#/components/schemas/BetaManagedAgentsAdvisorParams'
          discriminator:
            propertyName: type
            mapping:
              agent:
                $ref: '#/components/schemas/BetaManagedAgentsAgentParams'
              self:
                $ref: '#/components/schemas/BetaManagedAgentsMultiagentSelfParams'
              advisor:
                $ref: '#/components/schemas/BetaManagedAgentsAdvisorParams'
    BetaManagedAgentsEffortLow:
      description: Low effort. Favors latency over reasoning depth.
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - low
    BetaManagedAgentsEffortMedium:
      description: Medium effort. Balances latency and reasoning depth.
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - medium
    BetaManagedAgentsEffortHigh:
      description: High effort. Favors reasoning depth.
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - high
    BetaManagedAgentsEffortXhigh:
      description: Extra-high effort. Not all models accept this level.
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - xhigh
    BetaManagedAgentsEffortMax:
      description: Maximum effort. Favors reasoning depth over latency.
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - max
    BetaManagedAgentsMultiagentRosterEntry:
      description: A resolved multiagent roster entry.
      discriminator:
        propertyName: type
        mapping:
          agent:
            $ref: '#/components/schemas/BetaManagedAgentsAgentReference'
          advisor:
            $ref: '#/components/schemas/BetaManagedAgentsAdvisor'
      oneOf:
        - $ref: '#/components/schemas/BetaManagedAgentsAgentReference'
        - $ref: '#/components/schemas/BetaManagedAgentsAdvisor'
    BetaManagedAgentsAgentToolConfig:
      description: Configuration for a specific agent tool.
      type: object
      additionalProperties: false
      required:
        - enabled
        - name
        - permission_policy
      properties:
        enabled:
          type: boolean
        name:
          $ref: '#/components/schemas/BetaManagedAgentsAgentToolName'
        permission_policy:
          $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy'
    BetaManagedAgentsAgentToolsetDefaultConfig:
      description: Resolved default configuration for agent tools.
      type: object
      additionalProperties: false
      required:
        - enabled
        - permission_policy
      properties:
        enabled:
          type: boolean
        permission_policy:
          $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy'
    BetaManagedAgentsMCPToolConfig:
      description: Resolved configuration for a specific MCP tool.
      type: object
      additionalProperties: false
      required:
        - enabled
        - name
        - permission_policy
      properties:
        enabled:
          type: boolean
        name:
          type: string
        permission_policy:
          $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy'
    BetaManagedAgentsMCPToolsetDefaultConfig:
      description: Resolved default configuration for all tools from an MCP server.
      type: object
      additionalProperties: false
      required:
        - enabled
        - permission_policy
      properties:
        enabled:
          type: boolean
        permission_policy:
          $ref: '#/components/schemas/BetaManagedAgentsPermissionPolicy'
    BetaManagedAgentsEffortLevel:
      type: string
      description: >-
        How hard the model works on each turn. Higher levels favor reasoning
        depth over latency. Not all models accept every level; invalid
        combinations are rejected at create time.
      enum:
        - low
        - medium
        - high
        - xhigh
        - max
    BetaManagedAgentsAgentToolName:
      type: string
      description: Built-in agent tool identifier.
      enum:
        - bash
        - edit
        - read
        - write
        - glob
        - grep
        - web_fetch
        - web_search
    BetaManagedAgentsPermissionPolicy:
      description: Permission policy for tool execution.
      type: object
      discriminator:
        propertyName: type
        mapping:
          always_allow:
            $ref: '#/components/schemas/BetaManagedAgentsAlwaysAllowPolicy'
          always_ask:
            $ref: '#/components/schemas/BetaManagedAgentsAlwaysAskPolicy'
      oneOf:
        - $ref: '#/components/schemas/BetaManagedAgentsAlwaysAllowPolicy'
        - $ref: '#/components/schemas/BetaManagedAgentsAlwaysAskPolicy'
    BetaManagedAgentsAgentParams:
      description: >-
        Specification for an Agent. Provide a specific `version` or use the
        short-form `agent="agent_id"` for the most recent version
      type: object
      additionalProperties: false
      required:
        - id
        - type
      properties:
        id:
          description: The `agent` ID.
          type: string
          minLength: 1
          maxLength: 128
        type:
          type: string
          enum:
            - agent
        version:
          description: >-
            The specific `agent` version to use. Omit to use the latest version.
            Must be at least 1 if specified.
          type: integer
          format: int32
    BetaManagedAgentsMultiagentSelfParams:
      description: >-
        Sentinel roster entry meaning "the agent that owns this configuration".
        Resolved server-side to a concrete agent reference.
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - self
          examples:
            - self
      example:
        type: self
    BetaManagedAgentsAdvisorParams:
      description: >-
        Platform advisor roster entry: a model the session's primary thread may
        consult mid-turn. At most one per roster; the entry occupies the roster
        name `anthropic.advisor`.
      type: object
      additionalProperties: false
      required:
        - model
        - type
      properties:
        model:
          description: >-
            Advisor model ID. The model must be permitted as an advisor for this
            agent's model—see the sessions/threads/advisor specification.
          type: string
          minLength: 1
          maxLength: 256
          examples:
            - claude-fable-5
        type:
          type: string
          enum:
            - advisor
          examples:
            - advisor
      example:
        type: advisor
        model: claude-fable-5
    BetaManagedAgentsAgentReference:
      description: A resolved agent reference with a concrete version.
      type: object
      additionalProperties: false
      required:
        - id
        - type
        - version
      properties:
        id:
          type: string
          examples:
            - agent_011CZkYqphY8vELVzwCUpqiQ
        type:
          type: string
          enum:
            - agent
          examples:
            - agent
        version:
          type: integer
          format: int32
          examples:
            - 1
      example:
        type: agent
        id: agent_011CZkYqphY8vELVzwCUpqiQ
        version: 1
    BetaManagedAgentsAdvisor:
      description: >-
        Platform advisor roster entry: a model the session's primary thread may
        consult mid-turn.
      type: object
      additionalProperties: false
      required:
        - model
        - type
      properties:
        model:
          description: The advisor model id.
          type: string
        type:
          type: string
          enum:
            - advisor
    BetaManagedAgentsAlwaysAllowPolicy:
      description: Tool calls are automatically approved without user confirmation.
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - always_allow
    BetaManagedAgentsAlwaysAskPolicy:
      description: Tool calls require user confirmation before execution.
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - always_ask
  securitySchemes:
    omaApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: OMA workspace API key.
      x-default: sk-ant-local-default
    omaBearer:
      type: http
      scheme: bearer
      description: OMA workspace API key sent as a bearer token.

````