> ## 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.

# Create Agent

> Create Agent through the OMA API.

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


## OpenAPI

````yaml /openapi/oma.en.json post /v1/agents
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:
    post:
      summary: Create Agent
      operationId: BetaCreateAgent
      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
            default: true
          example: 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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BetaManagedAgentsCreateAgentParams'
            example:
              model: claude-sonnet-4-6
              name: My First Agent
              description: A general-purpose starter agent.
              metadata:
                foo: bar
              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:
                - type: agent_toolset_20260401
      responses:
        '200':
          description: Successful response (OK)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsAgent'
              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
        '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'
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl --request POST \
              --url 'http://localhost:38080/v1/agents?beta=true' \
              --header 'Content-Type: application/json' \
              --header 'anthropic-version: 2023-06-01' \
              --header 'anthropic-beta: managed-agents-2026-04-01' \
              --header 'X-Api-Key: sk-ant-local-default' \
              --data '{
                "model": "claude-sonnet-4-6",
                "name": "My First Agent",
                "description": "A general-purpose starter agent.",
                "metadata": {
                  "foo": "bar"
                },
                "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": [
                  {
                    "type": "agent_toolset_20260401"
                  }
                ]
              }'
components:
  schemas:
    BetaManagedAgentsCreateAgentParams:
      description: Request parameters for creating an `agent`.
      type: object
      additionalProperties: false
      required:
        - model
        - name
      properties:
        model:
          description: >-
            Model identifier. Accepts the model string, e.g. `claude-opus-4-6`,
            or a `model_config` object for additional configuration control
          allOf:
            - $ref: '#/components/schemas/BetaManagedAgentsModelParams'
          examples:
            - claude-sonnet-4-6
        name:
          description: Human-readable name for the agent.
          type: string
          minLength: 1
          maxLength: 256
          examples:
            - My First Agent
        description:
          description: Description of what the agent does.
          type: string
          maxLength: 2048
          nullable: true
          examples:
            - A general-purpose starter agent.
        mcp_servers:
          description: >-
            MCP servers this agent connects to. Maximum 20. Names must be unique
            within the array. Every server must be referenced by an
            `mcp_toolset` in `tools`; unreferenced servers are rejected. See the
            MCP connector guide.
          type: array
          items:
            $ref: '#/components/schemas/BetaManagedAgentsMCPServerParams'
        metadata:
          description: >-
            Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars,
            values up to 512 chars.
          type: object
          additionalProperties:
            type: string
          examples:
            - foo: bar
        multiagent:
          description: >-
            Multiagent orchestration configuration. Currently supports the
            `coordinator` topology with a roster of 1-20 agents.
          allOf:
            - $ref: '#/components/schemas/BetaManagedAgentsMultiagentParams'
          nullable: true
        skills:
          description: Skills available to the agent.
          type: array
          items:
            $ref: '#/components/schemas/BetaManagedAgentsSkillParams'
        system:
          description: System prompt for the agent.
          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. Maximum of 128 tools
            across all toolsets allowed.
          type: array
          items:
            $ref: '#/components/schemas/BetaManagedAgentsAgentToolParams'
          examples:
            - - type: agent_toolset_20260401
      example:
        model: claude-sonnet-4-6
        name: My First Agent
        description: A general-purpose starter agent.
        metadata:
          foo: bar
        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:
          - type: agent_toolset_20260401
    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'
    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'
    BetaManagedAgentsMultiagentParams:
      description: >-
        Multiagent orchestration configuration. Currently supports the
        `coordinator` topology.
      discriminator:
        propertyName: type
        mapping:
          coordinator:
            $ref: '#/components/schemas/BetaManagedAgentsMultiagentCoordinatorParams'
      oneOf:
        - $ref: '#/components/schemas/BetaManagedAgentsMultiagentCoordinatorParams'
    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'
    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'
    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
    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
    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
    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'
    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
    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'
    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'
    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
    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
    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
    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'
    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.

````