> ## Documentation Index
> Fetch the complete documentation index at: https://browseruse-0aece648-larsen-v1-unified-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List Agents

> List the agents this platform exposes — the routing truth.

Each entry carries `capabilities` + `session.kind` (structured routing signal)
plus `best_for` / `not_for` / `example_tasks` hints and the `run` endpoint.
The run BODY schema lives in the OpenAPI spec, not here. Filter with
`?capability=` (e.g. `code` → only agents that can run code).



## OpenAPI

````yaml /cloud/openapi/v1.json get /agents
openapi: 3.1.0
info:
  title: Browser Use API v1
  summary: Unified /api/v1 preview spec, non-production only
  version: 1.0.0
servers:
  - url: https://api-staging-ufcbwvyv9yifyyvc3.browser-use.com/api/v1
    description: Browser Use API v1 (staging)
security: []
paths:
  /agents:
    get:
      tags:
        - Agents
      summary: List Agents
      description: >-
        List the agents this platform exposes — the routing truth.


        Each entry carries `capabilities` + `session.kind` (structured routing
        signal)

        plus `best_for` / `not_for` / `example_tasks` hints and the `run`
        endpoint.

        The run BODY schema lives in the OpenAPI spec, not here. Filter with

        `?capability=` (e.g. `code` → only agents that can run code).
      operationId: list_agents_agents_get
      parameters:
        - name: capability
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/Capability'
              - type: 'null'
            description: >-
              Filter to agents that expose this capability, e.g.
              ?capability=code.
            title: Capability
          description: Filter to agents that expose this capability, e.g. ?capability=code.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentList'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    Capability:
      type: string
      enum:
        - browser
        - code
        - terminal
        - files
      title: Capability
      description: >-
        The closed set of agent capabilities — the registry's routing TRUTH.


        `capabilities` on an agent is platform-enforced: sending `workspace_id`
        to an

        agent that lacks `files` → 400 naming the right agent. Both agents do

        `browser` + `files`; the only structural difference is `code` /
        `terminal`

        (browsercode).
    AgentList:
      properties:
        agents:
          items:
            $ref: '#/components/schemas/AgentInfo'
          type: array
          title: Agents
      type: object
      required:
        - agents
      title: AgentList
      description: >-
        The registry: every agent this platform exposes.


        Not paginated — the agent list is tiny and fully enumerable. A plain
        array so

        an LLM can read the whole routing table in one call.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentInfo:
      properties:
        name:
          type: string
          enum:
            - browser-use
            - browsercode
          title: Name
          description: The agent's stable name, used in its route path.
        capabilities:
          items:
            $ref: '#/components/schemas/Capability'
          type: array
          title: Capabilities
          description: >-
            Closed, platform-enforced capability set. Sending an input a
            capability gates (e.g. workspaceId without `files`) → 400 naming the
            right agent.
        session:
          $ref: '#/components/schemas/AgentSessionInfo'
          description: How this agent handles conversations/sessions.
        bestFor:
          type: string
          title: Bestfor
          description: When to reach for this agent (natural-language hint).
        notFor:
          type: string
          title: Notfor
          description: When NOT to use this agent; reach for the other one.
        exampleTasks:
          items:
            type: string
          type: array
          title: Exampletasks
          description: Representative tasks this agent handles well.
        run:
          type: string
          title: Run
          description: The endpoint to POST a run to.
      type: object
      required:
        - name
        - capabilities
        - session
        - bestFor
        - notFor
        - exampleTasks
        - run
      title: AgentInfo
      description: >-
        One agent's self-describing registry entry.


        `capabilities` + `session.kind` are the structured routing TRUTH.

        `best_for` / `not_for` / `example_tasks` are natural-language hints that
        must

        stay in sync with them. `run` points at the create endpoint; the run
        BODY

        schema is NOT duplicated here — it lives in the OpenAPI spec.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    AgentSessionInfo:
      properties:
        kind:
          $ref: '#/components/schemas/SessionKind'
          description: >-
            `disposable` (task-scoped, browser and session share a lifetime) vs
            `durable` (long-horizon, session outlives its browsers). The
            strongest routing signal for "does this need to persist / extend".
      type: object
      required:
        - kind
      title: AgentSessionInfo
      description: How an agent's sessions behave — part of the registry descriptor.
    SessionKind:
      type: string
      enum:
        - disposable
        - durable
      title: SessionKind
      description: >-
        The strongest routing signal in the registry.


        `disposable` — task-scoped; the browser and the session share a lifetime

        (browser-use). `durable` — long-horizon; the session outlives its
        browsers

        and can be extended over many runs / returned to later (browsercode). An
        LLM

        branching on "does this need to persist / extend" reads THIS, not prose.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-Browser-Use-API-Key

````