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

# List sessions for an agent

> Return all sessions for an agent as enriched
:class:`SessionView` entries.

Each entry bundles three things the chat UI needs to render
without follow-up requests: the session record (incl.
``state``), whether a chat run is currently active, and — when
the session participates in a team — the resolved team detail
(leader agent + member agents with their session ids).

Args:
    agent_id (`str`):
        Agent whose sessions to list.
    user_id (`str`):
        Injected authenticated user ID.
    storage (`StorageBase`):
        Injected storage backend.
    message_bus (`MessageBus`):
        Injected message bus (used for ``session_is_running``).

Returns:
    `ListSessionsResponse`:
        Enriched session views and their count.

Raises:
    `HTTPException`: 404 if the agent does not exist or does not
        belong to the authenticated user.



## OpenAPI

````yaml /versions/2.0.2/en/deploy/openapi.json get /sessions/
openapi: 3.1.0
info:
  title: AgentScope
  version: 2.0.1
servers: []
security: []
paths:
  /sessions/:
    get:
      tags:
        - sessions
      summary: List sessions for an agent
      description: |-
        Return all sessions for an agent as enriched
        :class:`SessionView` entries.

        Each entry bundles three things the chat UI needs to render
        without follow-up requests: the session record (incl.
        ``state``), whether a chat run is currently active, and — when
        the session participates in a team — the resolved team detail
        (leader agent + member agents with their session ids).

        Args:
            agent_id (`str`):
                Agent whose sessions to list.
            user_id (`str`):
                Injected authenticated user ID.
            storage (`StorageBase`):
                Injected storage backend.
            message_bus (`MessageBus`):
                Injected message bus (used for ``session_is_running``).

        Returns:
            `ListSessionsResponse`:
                Enriched session views and their count.

        Raises:
            `HTTPException`: 404 if the agent does not exist or does not
                belong to the authenticated user.
      operationId: list_sessions_sessions__get
      parameters:
        - name: agent_id
          in: query
          required: true
          schema:
            type: string
            description: Filter sessions by agent ID.
            title: Agent Id
          description: Filter sessions by agent ID.
        - name: x-user-id
          in: header
          required: true
          schema:
            type: string
            description: >-
              Caller's user ID. Temporary header-based identity; will be
              replaced by JWT auth.
            title: X-User-Id
          description: >-
            Caller's user ID. Temporary header-based identity; will be replaced
            by JWT auth.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSessionsResponse'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ListSessionsResponse:
      properties:
        sessions:
          items:
            $ref: '#/components/schemas/SessionView'
          type: array
          title: Sessions
          description: Session views (record + is_running + team).
        total:
          type: integer
          title: Total
          description: Total number of sessions.
      type: object
      required:
        - sessions
        - total
      title: ListSessionsResponse
      description: Response body for listing sessions.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SessionView:
      properties:
        session:
          $ref: '#/components/schemas/SessionRecord'
          description: >-
            The persisted session record. Includes ``state``
            (``permission_context`` / ``tool_context`` / ``tasks_context``)
            inline.
        is_running:
          type: boolean
          title: Is Running
          description: Whether a chat run is currently active on this session.
        team:
          anyOf:
            - $ref: '#/components/schemas/TeamDetailResponse'
            - type: 'null'
          description: >-
            Resolved team detail when ``session.team_id`` is set (leader agent +
            member agents with their session ids). ``None`` when the session
            does not participate in any team.
      type: object
      required:
        - session
        - is_running
      title: SessionView
      description: |-
        Per-session bundle with everything the frontend needs to
        render either the list view or open a session.

        Bundles three orthogonal pieces of information so opening a
        session does not require a waterfall of follow-up requests:

        - the persisted :class:`SessionRecord` itself (config + state),
        - whether the session has an active chat run right now,
        - the team detail (resolved leader + members) when the session
          participates in a team.

        Messages are intentionally **not** included here — they are
        paginated separately via ``GET /sessions/{id}/messages``.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    SessionRecord:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the credential.
        updated_at:
          type: string
          format: date-time
          title: Updated At
        created_at:
          type: string
          format: date-time
          title: Created At
        user_id:
          type: string
          title: User Id
        agent_id:
          type: string
          title: Agent Id
        source:
          $ref: '#/components/schemas/SessionSource'
          default: user
        source_schedule_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Schedule Id
        team_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Team Id
        config:
          $ref: '#/components/schemas/SessionConfig'
        state:
          $ref: '#/components/schemas/AgentState'
      type: object
      required:
        - user_id
        - agent_id
        - config
      title: SessionRecord
      description: The session record.
    TeamDetailResponse:
      properties:
        team:
          $ref: '#/components/schemas/TeamRecord'
          description: The team record.
        leader_agent:
          anyOf:
            - $ref: '#/components/schemas/AgentRecord'
            - type: 'null'
          description: >-
            Leader's agent record (resolved from the team's ``session_id`` →
            session.agent_id).
        members:
          items:
            $ref: '#/components/schemas/TeamMemberView'
          type: array
          title: Members
          description: >-
            Worker agents listed in :attr:`TeamData.member_ids`, each paired
            with its single session id when available.
      type: object
      required:
        - team
      title: TeamDetailResponse
      description: Resolved team detail embedded inside :class:`SessionView.team`.
    SessionSource:
      type: string
      enum:
        - user
        - schedule
      title: SessionSource
      description: The source that created the session.
    SessionConfig:
      properties:
        workspace_id:
          type: string
          title: Workspace Id
        name:
          type: string
          title: Name
          description: Display name for the session.
        chat_model_config:
          anyOf:
            - $ref: '#/components/schemas/ChatModelConfig'
            - type: 'null'
        fallback_chat_model_config:
          anyOf:
            - $ref: '#/components/schemas/ChatModelConfig'
            - type: 'null'
      type: object
      required:
        - workspace_id
      title: SessionConfig
      description: Session configuration — set at creation, updatable via PATCH.
    AgentState:
      properties:
        session_id:
          type: string
          title: Session Id
        summary:
          anyOf:
            - type: string
            - items:
                anyOf:
                  - $ref: '#/components/schemas/TextBlock'
                  - $ref: '#/components/schemas/DataBlock'
              type: array
          title: Summary
          default: ''
        context:
          items:
            $ref: '#/components/schemas/Msg'
          type: array
          title: Context
        reply_id:
          type: string
          title: Reply Id
        cur_iter:
          type: integer
          title: Cur Iter
          default: 0
        permission_context:
          $ref: '#/components/schemas/PermissionContext'
        tool_context:
          $ref: '#/components/schemas/ToolContext'
        tasks_context:
          $ref: '#/components/schemas/TaskContext'
      type: object
      title: AgentState
      description: The agent state that should be saved and loaded from storage.
    TeamRecord:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the credential.
        updated_at:
          type: string
          format: date-time
          title: Updated At
        created_at:
          type: string
          format: date-time
          title: Created At
        user_id:
          type: string
          title: User Id
        session_id:
          type: string
          title: Session Id
        data:
          $ref: '#/components/schemas/TeamData'
      type: object
      required:
        - user_id
        - session_id
        - data
      title: TeamRecord
      description: |-
        The team ORM model.

        Team membership is session-level: the leader is identified by its
        ``session_id`` (since a user agent can lead multiple teams across
        different sessions). Workers are identified by their agent id in
        :attr:`TeamData.member_ids` (since workers have a 1:1 mapping between
        agent and session).
    AgentRecord:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the credential.
        updated_at:
          type: string
          format: date-time
          title: Updated At
        created_at:
          type: string
          format: date-time
          title: Created At
        user_id:
          type: string
          title: User Id
        source:
          type: string
          enum:
            - user
            - team
          title: Source
          default: user
        data:
          $ref: '#/components/schemas/AgentData'
      type: object
      required:
        - user_id
        - data
      title: AgentRecord
      description: The agent ORM model.
    TeamMemberView:
      properties:
        agent:
          $ref: '#/components/schemas/AgentRecord'
          description: The worker agent record.
        session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Session Id
          description: >-
            The worker's session id. ``None`` if the agent is in an inconsistent
            state (worker without a session).
      type: object
      required:
        - agent
      title: TeamMemberView
      description: |-
        One row in :attr:`TeamDetailResponse.members`.

        Pairs each member's :class:`AgentRecord` with its single
        ``session_id`` so the UI can subscribe to the worker's chat
        stream without a separate lookup.
    ChatModelConfig:
      properties:
        type:
          type: string
          title: Type
        credential_id:
          type: string
          title: Credential Id
        model:
          type: string
          title: Model
        parameters:
          additionalProperties: true
          type: object
          title: Parameters
      type: object
      required:
        - type
        - credential_id
        - model
        - parameters
      title: ChatModelConfig
      description: The model configuration class.
    TextBlock:
      properties:
        type:
          type: string
          const: text
          title: Type
          default: text
        text:
          type: string
          title: Text
        id:
          type: string
          title: Id
      type: object
      required:
        - text
      title: TextBlock
      description: The text block.
    DataBlock:
      properties:
        type:
          type: string
          const: data
          title: Type
          default: data
        id:
          type: string
          title: Id
        source:
          anyOf:
            - $ref: '#/components/schemas/Base64Source'
            - $ref: '#/components/schemas/URLSource'
          title: Source
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
      type: object
      required:
        - source
      title: DataBlock
      description: The data block for binary content (images, audio, video, etc.).
    Msg:
      properties:
        name:
          type: string
          title: Name
        content:
          items:
            anyOf:
              - $ref: '#/components/schemas/TextBlock'
              - $ref: '#/components/schemas/ThinkingBlock'
              - $ref: '#/components/schemas/HintBlock'
              - $ref: '#/components/schemas/ToolCallBlock'
              - $ref: '#/components/schemas/ToolResultBlock'
              - $ref: '#/components/schemas/DataBlock'
          type: array
          title: Content
        role:
          type: string
          enum:
            - user
            - assistant
            - system
          title: Role
        id:
          type: string
          title: Id
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        created_at:
          type: string
          title: Created At
        finished_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Finished At
        usage:
          anyOf:
            - $ref: '#/components/schemas/Usage'
            - type: 'null'
      type: object
      required:
        - name
        - content
        - role
      title: Msg
      description: |-
        The message class in AgentScope, responsible for information storage
        and transmission among different agents.
    PermissionContext:
      properties:
        mode:
          $ref: '#/components/schemas/PermissionMode'
          default: default
        working_directories:
          additionalProperties:
            $ref: '#/components/schemas/AdditionalWorkingDirectory'
          type: object
          title: Working Directories
        allow_rules:
          additionalProperties:
            items:
              $ref: '#/components/schemas/PermissionRule'
            type: array
          type: object
          title: Allow Rules
        deny_rules:
          additionalProperties:
            items:
              $ref: '#/components/schemas/PermissionRule'
            type: array
          type: object
          title: Deny Rules
        ask_rules:
          additionalProperties:
            items:
              $ref: '#/components/schemas/PermissionRule'
            type: array
          type: object
          title: Ask Rules
      type: object
      title: PermissionContext
      description: |-
        Context for permission checking.

        Contains the permission mode, working directories, and all configured
        permission rules organized by behavior type (allow, deny, ask).
    ToolContext:
      properties:
        max_cache_files:
          type: integer
          exclusiveMinimum: 1
          title: Max Cache Files
          default: 100
        max_cache_bytes:
          type: number
          exclusiveMinimum: 10000
          title: Max Cache Bytes
          default: 25000
        read_file_cache:
          items:
            $ref: '#/components/schemas/ReadCacheEntry'
          type: array
          title: Read File Cache
        activated_groups:
          items:
            type: string
          type: array
          title: Activated Groups
      type: object
      title: ToolContext
      description: The tool context, e.g. tool cache
    TaskContext:
      properties:
        tasks:
          items:
            $ref: '#/components/schemas/Task'
          type: array
          title: Tasks
      type: object
      title: TaskContext
      description: The task context.
    TeamData:
      properties:
        name:
          type: string
          title: Name
          description: Display name of the team.
        description:
          type: string
          title: Description
          description: >-
            What the team is for — its overall goal or shared context. Wired
            into every member's system prompt so all members share the same
            high-level understanding of why the team exists.
          default: ''
        member_ids:
          items:
            type: string
          type: array
          title: Member Ids
          description: >-
            Worker agent ids that belong to this team. Each worker has
            ``source='team'`` and exactly one session, so the agent id uniquely
            identifies the member; the session can be looked up via
            :meth:`StorageBase.list_sessions`.
      type: object
      required:
        - name
      title: TeamData
      description: The team data model.
    AgentData:
      properties:
        id:
          type: string
          title: Id
          description: Unique agent id
        name:
          type: string
          title: Name
          description: The name of the agent.
        system_prompt:
          type: string
          format: textarea
          title: System Prompt
          description: The system prompt for the agent.
          default: You're a helpful assistant.
        context_config:
          $ref: '#/components/schemas/ContextConfig'
          title: Context Config
          description: The context config for the agent.
        react_config:
          $ref: '#/components/schemas/ReActConfig'
          title: React Config
          description: The react config for the agent.
      type: object
      required:
        - name
        - context_config
        - react_config
      title: AgentData
      description: The agent data model.
    Base64Source:
      properties:
        type:
          type: string
          const: base64
          title: Type
          default: base64
        data:
          type: string
          title: Data
        media_type:
          type: string
          title: Media Type
      type: object
      required:
        - data
        - media_type
      title: Base64Source
      description: The base64 source.
    URLSource:
      properties:
        type:
          type: string
          const: url
          title: Type
          default: url
        url:
          type: string
          minLength: 1
          format: uri
          title: Url
        media_type:
          type: string
          title: Media Type
      type: object
      required:
        - url
        - media_type
      title: URLSource
      description: The URL source.
    ThinkingBlock:
      properties:
        type:
          type: string
          const: thinking
          title: Type
          default: thinking
        thinking:
          type: string
          title: Thinking
        id:
          type: string
          title: Id
      additionalProperties: true
      type: object
      required:
        - thinking
      title: ThinkingBlock
      description: |-
        The thinking block.

        Allows extra provider-specific fields (e.g. Anthropic's ``signature``)
        via ``extra="allow"`` so that model implementations can pass
        arbitrary metadata without subclassing.
    HintBlock:
      properties:
        type:
          type: string
          const: hint
          title: Type
          default: hint
        hint:
          anyOf:
            - type: string
            - items:
                anyOf:
                  - $ref: '#/components/schemas/TextBlock'
                  - $ref: '#/components/schemas/DataBlock'
              type: array
          title: Hint
        id:
          type: string
          title: Id
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
      type: object
      required:
        - hint
      title: HintBlock
      description: |-
        A block used to provide instructions or hints to the LLM during the
        reasoning-acting loop. When passed to the LLM API, the hint block is
        converted into a user message.

        The ``hint`` field can be a plain string (text-only) or a list of
        :class:`TextBlock` / :class:`DataBlock` for multimodal content
        (e.g. a background tool result containing both text and an image).
    ToolCallBlock:
      properties:
        type:
          type: string
          const: tool_call
          title: Type
          default: tool_call
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        input:
          type: string
          title: Input
        state:
          $ref: '#/components/schemas/ToolCallState'
          default: pending
        suggested_rules:
          items:
            $ref: '#/components/schemas/PermissionRule'
          type: array
          title: Suggested Rules
      additionalProperties: true
      type: object
      required:
        - id
        - name
        - input
      title: ToolCallBlock
      description: |-
        The tool call block.

        Allows extra provider-specific fields (e.g. the OpenAI Responses API's
        ``call_id``) via ``extra="allow"`` without requiring subclassing.
    ToolResultBlock:
      properties:
        type:
          type: string
          const: tool_result
          title: Type
          default: tool_result
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        output:
          anyOf:
            - type: string
            - items:
                anyOf:
                  - $ref: '#/components/schemas/TextBlock'
                  - $ref: '#/components/schemas/DataBlock'
              type: array
          title: Output
        state:
          $ref: '#/components/schemas/ToolResultState'
          default: running
      type: object
      required:
        - id
        - name
        - output
      title: ToolResultBlock
      description: The tool result block.
    Usage:
      properties:
        input_tokens:
          type: integer
          title: Input Tokens
        output_tokens:
          type: integer
          title: Output Tokens
      type: object
      required:
        - input_tokens
        - output_tokens
      title: Usage
      description: The token usage information of a message.
    PermissionMode:
      type: string
      enum:
        - default
        - accept_edits
        - explore
        - bypass
        - dont_ask
      title: PermissionMode
      description: >-
        The mode of permission.


        Permission modes control how the system handles tool execution requests.

        Different modes are suitable for different scenarios:


        +---------------+--------------------------------------------------+--------------------------------+

        | Mode          | Behavior                                         | Use
        Case                       |

        +===============+==================================================+================================+

        | DEFAULT       | All operations require explicit permission       |
        Default mode, most secure      |

        |               | (unless there are explicit allow rules)         
        |                                |

        +---------------+--------------------------------------------------+--------------------------------+

        | ACCEPT_EDITS  | - Auto-allow file writes in working directories | User
        present, rapid iteration  |

        |               | - Auto-allow file reads in working directories  |
        development                    |

        |               | - Auto-allow filesystem commands (mkdir, rm, mv)
        |                                |

        |               | - Other operations follow normal rules          
        |                                |

        +---------------+--------------------------------------------------+--------------------------------+

        | EXPLORE       | Read-only mode:                                  |
        Exploring codebase, planning   |

        |               | - Allow: Read, Grep, Glob (read-only tools)     |
        implementation                 |

        |               | - Deny: Write, Edit, Bash (modification tools) 
        |                                |

        +---------------+--------------------------------------------------+--------------------------------+

        | BYPASS        | All operations automatically allowed             |
        Testing environment, sandbox,  |

        |               | (no permission checks)                           |
        fully trusted scenarios        |

        +---------------+--------------------------------------------------+--------------------------------+

        | DONT_ASK      | Convert all ASK decisions to DENY                |
        Scheduled tasks, background    |

        |               | (user not available to answer prompts)           |
        execution when user is away    |

        +---------------+--------------------------------------------------+--------------------------------+


        Attributes:
            DEFAULT: Default mode - requires explicit permission for each action
            ACCEPT_EDITS: Accept edits mode - automatically allows file edits within working directories
            EXPLORE: Explore mode - read-only, no writes or command execution allowed
            BYPASS: Bypass mode - allows all actions without permission checks
            DONT_ASK: Don't ask mode - converts all ASK decisions to DENY (for unattended execution)
    AdditionalWorkingDirectory:
      properties:
        path:
          type: string
          title: Path
        source:
          type: string
          title: Source
      type: object
      required:
        - path
        - source
      title: AdditionalWorkingDirectory
      description: |-
        An additional directory included in permission scope.

        Working directories are used to determine which file paths should be
        automatically allowed in ACCEPT_EDITS mode.
    PermissionRule:
      properties:
        tool_name:
          type: string
          title: Tool Name
        rule_content:
          anyOf:
            - type: string
            - type: 'null'
          title: Rule Content
        behavior:
          $ref: '#/components/schemas/PermissionBehavior'
        source:
          type: string
          title: Source
      type: object
      required:
        - tool_name
        - rule_content
        - behavior
        - source
      title: PermissionRule
      description: >-
        Permission rule for tool usage.


        A permission rule defines whether a specific tool or tool operation

        should be allowed, denied, or require user confirmation. The

        rule_content field has different semantics depending on the tool_name:


        - For "Bash": rule_content is a substring pattern matched against the
          command Example: rule_content="npm install" matches "npm install express"

        - For "Write"/"Read": rule_content is a glob pattern matched against
        file
          paths Example: rule_content="src/**" matches "src/main.py"

        - For other tools: rule_content is a tool-specific filter pattern
    ReadCacheEntry:
      properties:
        lines:
          items:
            type: string
          type: array
          title: Lines
        updated_at:
          type: number
          title: Updated At
        bytes:
          type: number
          title: Bytes
        file_path:
          type: string
          title: File Path
      type: object
      required:
        - lines
        - updated_at
        - bytes
        - file_path
      title: ReadCacheEntry
      description: The read file cache.
    Task:
      properties:
        subject:
          type: string
          title: Subject
        description:
          type: string
          title: Description
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        created_at:
          type: string
          title: Created At
        state:
          type: string
          enum:
            - pending
            - in_progress
            - completed
          title: State
          default: pending
        id:
          type: string
          title: Id
        owner:
          anyOf:
            - type: string
            - type: 'null'
          title: Owner
        blocks:
          items:
            type: string
          type: array
          title: Blocks
        blocked_by:
          items:
            type: string
          type: array
          title: Blocked By
      type: object
      required:
        - subject
        - description
        - metadata
      title: Task
      description: The agent task.
    ContextConfig:
      properties:
        trigger_ratio:
          type: number
          exclusiveMaximum: 0.9
          exclusiveMinimum: 0
          title: Trigger Ratio
          default: 0.8
        reserve_ratio:
          type: number
          exclusiveMaximum: 0.9
          exclusiveMinimum: 0
          title: Reserve Ratio
          default: 0.1
        compression_prompt:
          type: string
          format: textarea
          title: Compression Prompt
          default: >-
            <system-hint>You have been working on the task described above but
            have not yet completed it. Now write a continuation summary that
            will allow you to resume work efficiently in a future context window
            where the conversation history will be replaced with this summary.
            Your summary should be structured, concise, and
            actionable.</system-hint>
        summary_template:
          type: string
          format: textarea
          title: Summary Template
          default: |-
            <system-info>Here is a summary of your previous work
            # Task Overview
            {task_overview}

            # Current State
            {current_state}

            # Important Discoveries
            {important_discoveries}

            # Next Steps
            {next_steps}

            # Context to Preserve
            {context_to_preserve}</system-info>
        summary_schema:
          additionalProperties: true
          type: object
          title: Summary Schema
        tool_result_limit:
          type: integer
          title: Tool Result Limit
          description: >-
            The maximum length of the tool results in tokens. If exceeded, the
            tool result will be truncated.
          default: 3000
      type: object
      title: ContextConfig
      description: The context related configuration in AgentScope
    ReActConfig:
      properties:
        max_iters:
          type: integer
          title: Max Iterations
          description: The maximum number of reasoning-acting iterations in one reply
          default: 20
        stop_on_reject:
          type: boolean
          title: Rejection Handling
          description: Whether to stop replying when being rejected to execute tools.
          default: false
      type: object
      title: ReActConfig
      description: The reasoning related configuration
    ToolCallState:
      type: string
      enum:
        - pending
        - asking
        - allowed
        - submitted
        - finished
      title: ToolCallState
      description: The state of the tool call.
    ToolResultState:
      type: string
      enum:
        - success
        - error
        - interrupted
        - denied
        - running
      title: ToolResultState
      description: The tool result state.
    PermissionBehavior:
      type: string
      enum:
        - allow
        - deny
        - ask
        - passthrough
      title: PermissionBehavior
      description: |-
        The behavior of permission.

        Attributes:
            ALLOW: Allow the operation
            DENY: Deny the operation
            ASK: Ask the user for permission
            PASSTHROUGH: Let the permission engine continue with rule matching
                (used by tools to defer decision to the engine)

````