openapi: 3.1.0
info:
  title: Computer-Use Agents Sessions API
  version: 1.0.0
servers:
- url: https://agp.eu.hcompany.ai
  description: Europe
  x-fern-server-name: Eu
- url: https://agp.hcompany.ai
  description: United States
  x-fern-server-name: Us
tags:
- name: Sessions
paths:
  /api/v2/sessions:
    post:
      tags:
      - Sessions
      summary: Create Session
      description: Create an agentic session.
      operationId: create_session_api_v2_sessions_post
      security:
      - HTTPBearer: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
            minLength: 1
            maxLength: 255
          - type: 'null'
          title: Idempotency-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Sessions
      summary: List Sessions
      description: List sessions visible to ``user``.
      operationId: list_sessions_api_v2_sessions_get
      security:
      - HTTPBearer: []
      parameters:
      - name: owner
        in: query
        required: false
        schema:
          enum:
          - me
          - me-in-organization
          - organization
          - me-or-organization
          type: string
          default: me-in-organization
          title: Owner
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/TrajectoryStatus'
          - type: 'null'
          title: Status
      - name: agent
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          title: Agent
      - name: group_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Group Id
      - name: parent_session_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Session Id
      - name: schedule_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Only sessions created by this schedule.
          title: Schedule Id
        description: Only sessions created by this schedule.
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Case-insensitive match on the session's first message or answer.
          title: Search
        description: Case-insensitive match on the session's first message or answer.
      - name: created_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created Before
      - name: created_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created After
      - name: finished_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Finished Before
      - name: finished_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Finished After
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number (1-based)
          default: 1
          title: Page
        description: Page number (1-based)
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Number of items per page
          default: 10
          title: Size
        description: Number of items per page
      - name: sort
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              enum:
              - created_at
              - -created_at
              type: string
          - type: 'null'
          description: Sort by field
          default:
          - -created_at
          title: Sort
        description: Sort by field
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_SessionSummary_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/sessions/quota:
    get:
      tags:
      - Sessions
      summary: Get Session Quota
      description: Concurrent-session quota for the authenticated user.
      operationId: get_session_quota_api_v2_sessions_quota_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaStatus'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v2/sessions/{id}:
    get:
      tags:
      - Sessions
      summary: Get Session
      description: Get a session.
      operationId: get_session_api_v2_sessions__id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Sessions
      summary: Cancel Session
      description: Cancel the session.
      operationId: cancel_session_api_v2_sessions__id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/sessions/{id}/status:
    get:
      tags:
      - Sessions
      summary: Get Session Status
      description: Get a session's live status.
      operationId: get_session_status_api_v2_sessions__id__status_get
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionStatus'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/sessions/{id}/messages:
    post:
      tags:
      - Sessions
      summary: Send Session Messages
      description: Send a user message (single or batch).
      operationId: send_session_messages_api_v2_sessions__id__messages_post
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/UserMessageEvent'
              - $ref: '#/components/schemas/UserMessageBatch'
              discriminator:
                propertyName: type
                mapping:
                  user_message: '#/components/schemas/UserMessageEvent'
                  batch: '#/components/schemas/UserMessageBatch'
              title: Input
      responses:
        '202':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/sessions/{id}/tool_results:
    post:
      tags:
      - Sessions
      summary: Send Session Tool Results
      description: Send results for custom tool calls (single or batch).
      operationId: send_session_tool_results_api_v2_sessions__id__tool_results_post
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/ToolResultEvent'
              - $ref: '#/components/schemas/ErrorEvent'
              - $ref: '#/components/schemas/ToolResultBatch'
              title: Input
      responses:
        '202':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/sessions/{id}/pause:
    post:
      tags:
      - Sessions
      summary: Pause Session
      description: Pause the session.
      operationId: pause_session_api_v2_sessions__id__pause_post
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '202':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/sessions/{id}/resume:
    post:
      tags:
      - Sessions
      summary: Resume Session
      description: Resume the session.
      operationId: resume_session_api_v2_sessions__id__resume_post
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '202':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/sessions/{id}/force_answer:
    post:
      tags:
      - Sessions
      summary: Force Session Answer
      description: Ask the agent to emit a final answer on its next step.
      operationId: force_session_answer_api_v2_sessions__id__force_answer_post
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '202':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/sessions/{id}/changes:
    get:
      tags:
      - Sessions
      summary: Get Session Changes
      description: Long-poll for new events since ``from_index``; 204 if none arrive within ``wait_for_seconds``.
      operationId: get_session_changes_api_v2_sessions__id__changes_get
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      - name: from_index
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: From Index
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 0
          - type: 'null'
          title: Limit
      - name: include_events
        in: query
        required: false
        schema:
          type: boolean
          default: true
          title: Include Events
      - name: wait_for_seconds
        in: query
        required: false
        schema:
          type: integer
          maximum: 25
          minimum: 0
          default: 0
          title: Wait For Seconds
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionChanges'
        '204':
          description: No changes since the specified index
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/sessions/{id}/events:
    get:
      tags:
      - Sessions
      summary: List Session Events
      description: Paginated event history. Use ``/changes`` for live tailing.
      operationId: list_session_events_api_v2_sessions__id__events_get
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Size
      - name: sort
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              enum:
              - timestamp
              - -timestamp
              type: string
          - type: 'null'
          title: Sort
      - name: type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Type
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_SessionEvent_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/sessions/{id}/feedback:
    post:
      tags:
      - Sessions
      summary: Submit Session Feedback
      description: Record semantic-success feedback on the whole session.
      operationId: submit_session_feedback_api_v2_sessions__id__feedback_post
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Feedback'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/sessions/{id}/events/{event_index}/feedback:
    put:
      tags:
      - Sessions
      summary: Submit Event Feedback
      description: Record feedback on a single event in the session's history.
      operationId: submit_event_feedback_api_v2_sessions__id__events__event_index__feedback_put
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      - name: event_index
        in: path
        required: true
        schema:
          type: integer
          title: Event Index
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Feedback'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/sessions/{id}/share:
    post:
      tags:
      - Sessions
      summary: Share Session
      description: Make the session publicly readable; returns the share URL path.
      operationId: share_session_api_v2_sessions__id__share_post
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareLink'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Sessions
      summary: Unshare Session
      description: Revoke public access to the session.
      operationId: unshare_session_api_v2_sessions__id__share_delete
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/sessions/{id}/resources/{bucket}/{key}:
    get:
      tags:
      - Sessions
      summary: Get Session Resource
      description: Redirect to a presigned S3 URL for a session-owned resource.
      operationId: get_session_resource_api_v2_sessions__id__resources__bucket___key__get
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      - name: bucket
        in: path
        required: true
        schema:
          type: string
          title: Bucket
      - name: key
        in: path
        required: true
        schema:
          type: string
          title: Key
      responses:
        '302':
          description: Redirect to a presigned URL for a session-owned resource.
        '200':
          description: Resource bytes. The API redirects to a presigned S3 URL; SDK clients follow the redirect and receive the raw object (e.g. screenshot image bytes).
          content:
            application/octet-stream: {}
        '404':
          description: Session or resource not found.
        4XX:
          description: Client error.
components:
  schemas:
    Desktop:
      properties:
        id:
          type: string
          minLength: 1
          title: Id
          description: Catalog identifier for this environment.
        kind:
          type: string
          const: desktop
          title: Kind
          default: desktop
        host:
          type: string
          title: Host
          const: user_device
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
          description: Connect to an existing desktop session by id instead of starting a new one.
      type: object
      required:
      - id
      - host
      title: Desktop
      description: A desktop the agent controls via mouse, keyboard, and screenshots.
    PolicyEvent:
      properties:
        kind:
          type: string
          const: policy_event
          title: Kind
          default: policy_event
        reasoning_content:
          anyOf:
          - type: string
          - type: 'null'
          title: Reasoning Content
        content:
          anyOf:
          - type: string
          - type: 'null'
          title: Content
        tool_reqs:
          items:
            $ref: '#/components/schemas/ToolRequest'
          type: array
          title: Tool Reqs
        validation_errors:
          items:
            type: string
          type: array
          title: Validation Errors
          description: Validation errors raised while parsing the model output.
      type: object
      title: PolicyEvent
      description: 'One policy (LLM) step: the model output plus the tool requests extracted from it.'
    ActiveStateChangeEvent:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        type:
          type: string
          const: ActiveStateChangeEvent
          title: Type
        data:
          $ref: '#/components/schemas/ActiveStateChangeData'
      additionalProperties: true
      type: object
      required:
      - timestamp
      - type
      - data
      title: ActiveStateChangeEvent
      description: The agent switched between running, idle and awaiting custom tool results.
    Metrics:
      properties:
        steps:
          type: integer
          title: Steps
          description: Steps taken so far.
          default: 0
        cost_per_model:
          items:
            $ref: '#/components/schemas/ModelCost'
          type: array
          title: Cost Per Model
          description: Per-model token usage and cost.
        input_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Input Cost
          description: Total input cost in USD; null if any model is unpriced.
        output_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Output Cost
          description: Total output cost in USD; null if any model is unpriced.
        reasoning_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Reasoning Cost
          description: Total reasoning cost in USD; null if any model is unpriced.
        total_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Cost
          description: Total cost in USD; null if any model is unpriced.
      additionalProperties: true
      type: object
      title: Metrics
      description: Rolled-up usage and cost for a session.
    QuotaStatus:
      properties:
        scope:
          type: string
          enum:
          - user
          - org
          title: Scope
        limit:
          type: integer
          title: Limit
        active:
          type: integer
          title: Active
        available:
          type: integer
          title: Available
      type: object
      required:
      - scope
      - limit
      - active
      - available
      title: QuotaStatus
      description: Quota status.
    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
    TrajectoryEvent:
      properties:
        type:
          type: string
          title: Type
        data:
          title: Data
        timestamp:
          type: string
          format: date-time
          title: Timestamp
      type: object
      required:
      - type
      - data
      - timestamp
      title: TrajectoryEvent
      description: "Event from a trajectory.\n\nUnified from agp_client and agent_platform.\nUses the richer agent_platform version with screenshot serialization.\n\nEvents represent individual actions, observations, or state changes during\ntrajectory execution. They form a chronological log of everything that happened.\n\nCommon event types:\n- AgentStartedEvent: Agent begins execution\n- AgentCompletionEvent: Agent finishes successfully\n- AgentErrorEvent: Agent encounters an error\n- AgentEvent: Generic wrapper for agent-emitted events (policy_event, tool_result, observation_event)\n- LiveViewUrlEvent: Live view URL becomes available\n- ChatMessageEvent: Agent sends a chat message\n\nAttributes:\n    type: The type/name of the event (e.g., \"AgentStartedEvent\", \"AgentEvent\")\n    data: Event-specific data payload (structure varies by event type)\n    timestamp: When the event occurred"
    FlowEvent:
      properties:
        kind:
          type: string
          const: flow_event
          title: Kind
          default: flow_event
        flow:
          type: string
          title: Flow
          description: Control signal, e.g. "pause", "resume", "force_answer".
        origin:
          type: string
          title: Origin
          description: Who triggered the transition.
      type: object
      required:
      - flow
      - origin
      title: FlowEvent
      description: Run-loop control transition (pause, resume, stop, ...).
    AgentCompletionData:
      properties:
        reason:
          type: string
          enum:
          - finished
          - stopped
          - timed_out
          title: Reason
      additionalProperties: true
      type: object
      required:
      - reason
      title: AgentCompletionData
    ImageContent:
      properties:
        source:
          type: string
          title: Source
          description: 'Image location: a fetchable URL or a base64 payload, per ``type``.'
        type:
          type: string
          enum:
          - url
          - base64
          title: Type
        media_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Media Type
          description: MIME type, e.g. "image/png".
      type: object
      required:
      - source
      - type
      title: ImageContent
      description: 'Image payload: ``url`` for platform-served screenshots, ``base64`` for inline images.'
    ProxyPool:
      type: string
      enum:
      - residential
      - datacenter
      - isp
      - mobile
      title: ProxyPool
      description: The kind of upstream IPs a managed proxy draws from.
    ShareLink:
      properties:
        share_url:
          type: string
          title: Share Url
      additionalProperties: false
      type: object
      required:
      - share_url
      title: ShareLink
      description: Public share URL for a session.
    UserMessageBatch:
      properties:
        type:
          type: string
          const: batch
          title: Type
          default: batch
        messages:
          items:
            $ref: '#/components/schemas/UserMessageEvent'
          type: array
          minItems: 1
          title: Messages
      additionalProperties: false
      type: object
      required:
      - messages
      title: UserMessageBatch
      description: Batch of user messages.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SessionRequest:
      properties:
        agent:
          anyOf:
          - type: string
          - $ref: '#/components/schemas/Agent'
          title: Agent
          description: 'Agent to run: a registered agent''s name, or an inline Agent definition.'
        messages:
          anyOf:
          - type: string
          - $ref: '#/components/schemas/UserMessageEvent'
          - items:
              $ref: '#/components/schemas/UserMessageEvent'
            type: array
          - type: 'null'
          title: Messages
          description: Initial task for the agent. A plain string, a single message, or a list of messages.
        max_steps:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Max Steps
          description: Maximum reasoning steps the agent may take. Unbounded if null.
        max_time_s:
          anyOf:
          - type: number
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Max Time S
          description: Maximum wall-clock seconds the agent may run. Unbounded if null.
        idle_timeout_s:
          anyOf:
          - type: integer
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Idle Timeout S
          description: Seconds to keep the session open for follow-up messages after each answer. Null ends the session as soon as the agent answers.
        delete_after_min:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Delete After Min
          description: Minutes after the session finishes before it is automatically deleted. Defaults to 30 days. Null keeps the session forever.
          default: 43200
        delete_screenshot_after_min:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Delete Screenshot After Min
          description: Minutes after the session finishes before its screenshots are deleted. Defaults to 30 days. Null keeps screenshots for the session's lifetime.
          default: 43200
        queue:
          type: boolean
          title: Queue
          description: When the organization is at its concurrent-session limit, accept this session into a queue (status 'queued') instead of rejecting it with 429. Queued sessions start automatically, oldest first, as running sessions finish. Set to false to get an immediate 429 when no slot is available.
          default: true
        group_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Group Id
          description: Optional id to group and list related sessions together.
        parent_session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Session Id
          description: Id of the parent session, when this is a child run.
        overrides:
          additionalProperties: true
          type: object
          title: Overrides
          description: 'Per-run overrides applied to the resolved request, keyed by a dotted path. List members are selected with an explicit [field=value] clause, e.g. {"agent.environments[kind=web].start_url": "https://bing.com"}. Each value must match the type of the field its path targets.'
      type: object
      required:
      - agent
      title: SessionRequest
      description: '``POST /api/v2/sessions`` body.'
    Browser:
      properties:
        id:
          type: string
          minLength: 1
          title: Id
          description: Catalog identifier for this environment.
        kind:
          type: string
          const: web
          title: Kind
          default: web
        host:
          type: string
          enum:
          - user_device
          - cloud
          title: Host
          description: 'Where the browser runs: ''cloud'' on H Company infrastructure, or ''user_device'' on your own machine.'
          default: cloud
        start_url:
          type: string
          title: Start Url
          description: Initial URL to open.
          default: https://www.bing.com
        headless:
          type: boolean
          title: Headless
          description: Run the browser without a visible window.
          default: false
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
          description: Connect to an existing browser session by id instead of starting a new one.
        mode:
          oneOf:
          - $ref: '#/components/schemas/BrowserVisualMode'
          - $ref: '#/components/schemas/BrowserTextMode'
          title: Mode
          description: How the agent perceives and drives the browser.
          discriminator:
            propertyName: type
            mapping:
              text: '#/components/schemas/BrowserTextMode'
              visual: '#/components/schemas/BrowserVisualMode'
        vault_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Vault Id
          description: Id of a vault config to bind to this browser, letting the agent sign in to sites with secrets resolved from the vault. The vault must belong to the caller's organization. Only supported on cloud-hosted browsers. Omit to run without secret access.
        browser_profile_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Browser Profile Id
          description: Id of a browser profile to load into this browser, restoring saved cookies and storage state from a prior session. The profile must belong to the caller's organization. Only supported on cloud-hosted browsers. Omit to run with a fresh profile.
        use_default_browser_profile:
          type: boolean
          title: Use Default Browser Profile
          description: When true, load the caller's default browser profile for this browser flavor (marked via the browser-profiles API) instead of naming one explicitly. Mutually exclusive with browser_profile_id. When no default exists, an empty profile is auto-created and marked default; default-profile sessions save their final state back on stop when no other session is already persisting the profile. Only supported on cloud-hosted browsers.
          default: false
        persist_browser_profile:
          type: boolean
          title: Persist Browser Profile
          description: When true, the browser profile is updated with this session's final browser state (cookies, storage) when the session ends. Requires browser_profile_id or use_default_browser_profile. Only one active session at a time may persist a given profile; concurrent read-only use is always allowed.
          default: false
        network:
          anyOf:
          - $ref: '#/components/schemas/BrowserNetwork'
          - type: 'null'
          description: Optional network configuration for the remote browser session. Applied only when a new runner session is provisioned (not when session_id is set).
      type: object
      required:
      - id
      title: Browser
      description: A web browser the agent navigates and acts on.
    ToolResultBatch:
      properties:
        type:
          type: string
          const: batch
          title: Type
          default: batch
        results:
          items:
            oneOf:
            - $ref: '#/components/schemas/ToolResultEvent'
            - $ref: '#/components/schemas/ErrorEvent'
            discriminator:
              propertyName: kind
              mapping:
                error_event: '#/components/schemas/ErrorEvent'
                tool_result: '#/components/schemas/ToolResultEvent'
          type: array
          minItems: 1
          title: Results
      additionalProperties: false
      type: object
      required:
      - results
      title: ToolResultBatch
      description: Batch of custom tool results.
    AnswerEvent:
      properties:
        kind:
          type: string
          const: answer_event
          title: Kind
          default: answer_event
        answer:
          anyOf:
          - type: string
          - additionalProperties: true
            type: object
          title: Answer
          description: Final answer, plain text or structured JSON; any embedded image is inlined as base64, not a URL.
        outcome:
          anyOf:
          - $ref: '#/components/schemas/AnswerOutcome'
          - type: 'null'
          description: Agent's self-assessment of the task outcome; null when the agent did not report one.
      type: object
      required:
      - answer
      title: AnswerEvent
      description: Agent's final answer for the current task.
    SessionEvent:
      anyOf:
      - oneOf:
        - $ref: '#/components/schemas/AgentStartedEvent'
        - $ref: '#/components/schemas/AgentCompletionEvent'
        - $ref: '#/components/schemas/AgentErrorEvent'
        - $ref: '#/components/schemas/AgentRunStatusChangeEvent'
        - $ref: '#/components/schemas/ActiveStateChangeEvent'
        - $ref: '#/components/schemas/LiveViewUrlEvent'
        - $ref: '#/components/schemas/RequestStartEvent'
        - $ref: '#/components/schemas/RequestStartDispatchedEvent'
        - $ref: '#/components/schemas/MetricsUpdateEvent'
        - $ref: '#/components/schemas/AgentEvent'
        discriminator:
          propertyName: type
          mapping:
            ActiveStateChangeEvent: '#/components/schemas/ActiveStateChangeEvent'
            AgentCompletionEvent: '#/components/schemas/AgentCompletionEvent'
            AgentErrorEvent: '#/components/schemas/AgentErrorEvent'
            AgentEvent: '#/components/schemas/AgentEvent'
            AgentRunStatusChangeEvent: '#/components/schemas/AgentRunStatusChangeEvent'
            AgentStartedEvent: '#/components/schemas/AgentStartedEvent'
            LiveViewUrlEvent: '#/components/schemas/LiveViewUrlEvent'
            MetricsUpdateEvent: '#/components/schemas/MetricsUpdateEvent'
            RequestStartDispatchedEvent: '#/components/schemas/RequestStartDispatchedEvent'
            RequestStartEvent: '#/components/schemas/RequestStartEvent'
      - $ref: '#/components/schemas/TrajectoryEvent'
    AgentStartedEvent:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        type:
          type: string
          const: AgentStartedEvent
          title: Type
        data:
          $ref: '#/components/schemas/AgentStartedData'
      additionalProperties: true
      type: object
      required:
      - timestamp
      - type
      - data
      title: AgentStartedEvent
      description: The agent process started.
    TrajectoryStatus:
      type: string
      enum:
      - queued
      - pending
      - running
      - paused
      - idle
      - awaiting_tool_results
      - completed
      - failed
      - timed_out
      - interrupted
      title: TrajectoryStatus
      description: "State of a session/trajectory.\n\nLifecycle::\n\n    QUEUED → PENDING → RUNNING → {COMPLETED, FAILED, TIMED_OUT, INTERRUPTED}\n       |        |        ↑  ↑ ↑\n       |        |        |  | └───→ IDLE (interactive: agent waiting for next task)\n       |        |        |  └─────→ AWAITING_TOOL_RESULTS (waiting for custom tool results)\n       |        |        ↓\n       |        └─────→ PAUSED\n       └────→ INTERRUPTED (cancelled before launch)\n\nQUEUED sessions were accepted above the org's concurrency quota and wait,\nunprovisioned, until a running session finishes."
    RequestStartEvent:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        type:
          type: string
          const: RequestStartEvent
          title: Type
        data:
          $ref: '#/components/schemas/RequestStartData'
      additionalProperties: true
      type: object
      required:
      - timestamp
      - type
      - data
      title: RequestStartEvent
      description: The platform requested the agent to start.
    AgentRunStatusChangeEvent:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        type:
          type: string
          const: AgentRunStatusChangeEvent
          title: Type
        data:
          $ref: '#/components/schemas/AgentRunStatusChangeData'
      additionalProperties: true
      type: object
      required:
      - timestamp
      - type
      - data
      title: AgentRunStatusChangeEvent
      description: The run status changed.
    Environment:
      oneOf:
      - $ref: '#/components/schemas/Browser'
      - $ref: '#/components/schemas/Desktop'
      discriminator:
        propertyName: kind
        mapping:
          desktop: '#/components/schemas/Desktop'
          web: '#/components/schemas/Browser'
    LiveViewUrlEvent:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        type:
          type: string
          const: LiveViewUrlEvent
          title: Type
        data:
          $ref: '#/components/schemas/LiveViewUrlData'
      additionalProperties: true
      type: object
      required:
      - timestamp
      - type
      - data
      title: LiveViewUrlEvent
      description: A live view URL became available.
    BrowserVisualMode:
      properties:
        type:
          type: string
          const: visual
          title: Type
          default: visual
        width:
          type: integer
          exclusiveMinimum: 0.0
          title: Width
          description: Viewport width in pixels.
          default: 1200
        height:
          type: integer
          exclusiveMinimum: 0.0
          title: Height
          description: Viewport height in pixels.
          default: 1200
        markdown:
          type: boolean
          title: Markdown
          description: Also include the viewport's text as markdown alongside each screenshot.
          default: false
      type: object
      title: BrowserVisualMode
      description: Act on screenshots by viewport coordinates.
    SessionSummary:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        agent:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent
        status:
          $ref: '#/components/schemas/TrajectoryStatus'
        agent_view_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent View Url
          description: URL of the session's Agent View page on the H Platform (live view and replay).
        first_message:
          anyOf:
          - $ref: '#/components/schemas/UserMessageEvent'
          - type: 'null'
        created_at:
          type: string
          format: date-time
          title: Created At
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
        finished_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Finished At
        anonymized_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Anonymized At
          description: When the session's PII text and screenshots were irreversibly anonymized. Null if not anonymized.
      additionalProperties: false
      type: object
      required:
      - id
      - status
      - created_at
      title: SessionSummary
      description: Flat projection for session listings, including child rosters via ``?parent_session_id=``.
    Page_SessionEvent_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/SessionEvent'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
      type: object
      required:
      - items
      - total
      - page
      title: Page[SessionEvent]
    Agent:
      properties:
        name:
          type: string
          maxLength: 127
          minLength: 1
          title: Name
          description: 'Unique name for this agent in your catalog. Format: lowercase ASCII letters, digits and hyphens; must start and end with alphanumeric; max 63 chars per segment; optional single ''org/'' namespace prefix (e.g. ''h/web-environment'').'
        description:
          type: string
          minLength: 1
          title: Description
          description: What the agent does. Parent agents read this to decide when to delegate to it.
        environments:
          items:
            anyOf:
            - type: string
            - $ref: '#/components/schemas/Environment'
          type: array
          title: Environments
          description: Environments the agent runs in. Each entry is a registered environment's id or an inline definition. At most one per kind. Required unless the agent delegates to subagents (a pure orchestrator owns none).
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: Model that serves the agent. Defaults to the platform model if omitted.
        instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Instructions
          description: Instructions appended to the agent's system prompt to steer behavior.
        subagents:
          anyOf:
          - items:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/Agent'
            type: array
          - type: 'null'
          title: Subagents
          description: Agents this one can delegate to. Each entry is a registered agent's name or an inline definition.
        skills:
          anyOf:
          - items:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/Skill'
            type: array
          - type: 'null'
          title: Skills
          description: Skills the agent can draw on. Each entry is a registered skill's name or an inline definition.
        answer_format:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Answer Format
          description: JSON Schema the agent's final answer must conform to. Null returns a free-form text answer.
        tools:
          anyOf:
          - items:
              $ref: '#/components/schemas/ToolDefinition'
            type: array
          - type: 'null'
          title: Tools
          description: Custom tools executed by the API client. The agent emits a tool call, pauses, and resumes once the client sends back the matching tool result.
      type: object
      required:
      - name
      - description
      - environments
      title: Agent
      description: Declarative agent definition.
    MetricsUpdateData:
      properties:
        metrics:
          $ref: '#/components/schemas/Metrics'
      additionalProperties: true
      type: object
      required:
      - metrics
      title: MetricsUpdateData
    RequestStartData:
      properties: {}
      additionalProperties: true
      type: object
      title: RequestStartData
      description: Empty payload.
    JsonValue: {}
    AgentErrorEvent:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        type:
          type: string
          const: AgentErrorEvent
          title: Type
        data:
          $ref: '#/components/schemas/AgentErrorData'
      additionalProperties: true
      type: object
      required:
      - timestamp
      - type
      - data
      title: AgentErrorEvent
      description: The agent run failed.
    ErrorEvent:
      properties:
        kind:
          type: string
          const: error_event
          title: Kind
          default: error_event
        error:
          type: string
          title: Error
        origin:
          type: string
          title: Origin
          description: Component that raised the error.
        tool_req:
          anyOf:
          - $ref: '#/components/schemas/ToolRequest'
          - type: 'null'
          description: Tool request being executed, if any.
      type: object
      required:
      - error
      - origin
      title: ErrorEvent
      description: Recoverable error raised while running the agent loop.
    Feedback:
      properties:
        success:
          type: boolean
          title: Success
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
      type: object
      required:
      - success
      title: Feedback
      description: Feedback on the semantic success of the trajectory.
    BrowserNetwork:
      properties:
        proxy_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Proxy Url
          description: Optional bring-your-own HTTP/HTTPS/SOCKS proxy URL for browser egress (e.g. http://user:pass@proxy.example.com:8080). Applied when provisioning a new remote browser session. Only supported for chromium-based browser runners (headful and headless). Ignored when session_id attaches to an existing session. Mutually exclusive with managed_proxy.
        managed_proxy:
          anyOf:
          - $ref: '#/components/schemas/ManagedProxySelection'
          - type: 'null'
          description: Optional H-managed proxy (e.g. Oxylabs), provisioned for the session. Applied when provisioning a new remote browser session. Only supported for chromium-based browser runners (headful and headless). Ignored when session_id attaches to an existing session. Mutually exclusive with proxy_url.
      type: object
      title: BrowserNetwork
      description: Network egress settings for a remote browser session.
    ToolRequest:
      properties:
        tool_name:
          type: string
          title: Tool Name
        args:
          additionalProperties: true
          type: object
          title: Args
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
          description: Identifier correlating the request with its result.
      type: object
      required:
      - tool_name
      title: ToolRequest
      description: Tool invocation proposed by the policy.
    Skill:
      properties:
        name:
          type: string
          minLength: 1
          title: Name
          description: 'Unique name for this skill in your catalog. Format: lowercase ASCII letters, digits and hyphens; must start and end with alphanumeric; max 63 chars per segment; optional single ''org/'' namespace prefix (e.g. ''h/web-environment'').'
        description:
          type: string
          minLength: 1
          title: Description
          description: When to use this skill. The agent reads this to decide whether to load it.
        body:
          type: string
          minLength: 1
          title: Body
          description: Markdown instructions the agent loads when it uses the skill.
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
          description: Optional URL the content was sourced from.
        url_pattern:
          anyOf:
          - type: string
            maxLength: 1024
            minLength: 1
          - type: 'null'
          title: Url Pattern
          description: Optional regex hinting at URLs where this skill applies.
      type: object
      required:
      - name
      - description
      - body
      title: Skill
      description: A named, reusable instruction an agent can draw on during a session.
    Session:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        request:
          $ref: '#/components/schemas/SessionRequest'
        status:
          $ref: '#/components/schemas/SessionStatus'
        agent_view_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent View Url
          description: URL of the session's Agent View page on the H Platform (live view and replay).
        latest_answer:
          title: Latest Answer
          description: 'The agent''s most recent final answer: free-form text, or structured data when the agent runs with a custom answer format. Null until the agent first answers. Mirrors the answer streamed from the changes endpoint, surfaced here for non-interactive runs.'
        created_at:
          type: string
          format: date-time
          title: Created At
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
        finished_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Finished At
      additionalProperties: false
      type: object
      required:
      - id
      - request
      - status
      - created_at
      title: Session
      description: 'Full session envelope: original request + live status.'
    ToolResultEvent:
      properties:
        kind:
          type: string
          const: tool_result
          title: Kind
          default: tool_result
        tool_req:
          $ref: '#/components/schemas/ToolRequest'
        result:
          $ref: '#/components/schemas/JsonValue'
          description: Tool output as opaque JSON; any embedded image is inlined as base64, not a URL.
      type: object
      required:
      - tool_req
      title: ToolResultEvent
      description: Result of executing one tool request.
    BrowserTextMode:
      properties:
        type:
          type: string
          const: text
          title: Type
          default: text
        chunk_size:
          type: integer
          exclusiveMinimum: 0.0
          title: Chunk Size
          description: Characters of page text shown per page.
          default: 20000
      type: object
      title: BrowserTextMode
      description: Read-only markdown with URL navigation, no screenshots.
    AgentCompletionEvent:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        type:
          type: string
          const: AgentCompletionEvent
          title: Type
        data:
          $ref: '#/components/schemas/AgentCompletionData'
      additionalProperties: true
      type: object
      required:
      - timestamp
      - type
      - data
      title: AgentCompletionEvent
      description: The agent run completed.
    MetricsUpdateEvent:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        type:
          type: string
          const: MetricsUpdateEvent
          title: Type
        data:
          $ref: '#/components/schemas/MetricsUpdateData'
      additionalProperties: true
      type: object
      required:
      - timestamp
      - type
      - data
      title: MetricsUpdateEvent
      description: Rolled-up usage and cost metrics for the session.
    MessageEvent:
      properties:
        kind:
          type: string
          const: message_event
          title: Kind
          default: message_event
        caller_id:
          type: string
          title: Caller Id
        content:
          items:
            anyOf:
            - type: string
            - $ref: '#/components/schemas/ImageContent'
          type: array
          title: Content
      type: object
      required:
      - caller_id
      title: MessageEvent
      description: Message exchanged with the agent (user, system or subagent).
    ModelUsage:
      properties:
        name:
          type: string
          title: Name
          description: Model id.
        input_tokens:
          type: integer
          title: Input Tokens
          description: Input tokens consumed.
        output_tokens:
          type: integer
          title: Output Tokens
          description: Output tokens produced.
        reasoning_tokens:
          type: integer
          title: Reasoning Tokens
          description: Reasoning tokens produced.
      type: object
      required:
      - name
      - input_tokens
      - output_tokens
      - reasoning_tokens
      title: ModelUsage
      description: Per-model token usage.
    ManagedProxySelection:
      properties:
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
          description: Two-letter ISO 3166-1 country to source IPs from (e.g. 'US'). Validated server-side.
        sticky:
          type: boolean
          title: Sticky
          description: Keep the same IP across the session where the pool allows it.
          default: true
        pool:
          $ref: '#/components/schemas/ProxyPool'
          description: Which upstream IP pool to draw from.
          default: residential
      type: object
      title: ManagedProxySelection
      description: 'Request for an H-managed proxy, provisioned per session.


        Describes intent only — pool, country, stickiness — never credentials; H resolves

        and injects those when provisioning the session, including which provider backs

        the requested pool.'
    AgentStartedData:
      properties: {}
      additionalProperties: true
      type: object
      title: AgentStartedData
      description: Empty payload.
    Page_SessionSummary_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/SessionSummary'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
      type: object
      required:
      - items
      - total
      - page
      title: Page[SessionSummary]
    ModelCost:
      properties:
        name:
          type: string
          title: Name
          description: Model id.
        input_tokens:
          type: integer
          title: Input Tokens
          description: Input tokens consumed.
        output_tokens:
          type: integer
          title: Output Tokens
          description: Output tokens produced.
        reasoning_tokens:
          type: integer
          title: Reasoning Tokens
          description: Reasoning tokens produced.
        input_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Input Cost
          description: Input cost in USD; null if the model is unpriced.
        output_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Output Cost
          description: Output cost in USD; null if the model is unpriced.
        reasoning_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Reasoning Cost
          description: Reasoning cost in USD; null if the model is unpriced.
        total_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Cost
          description: Total cost in USD; null if the model is unpriced.
      additionalProperties: true
      type: object
      required:
      - name
      - input_tokens
      - output_tokens
      - reasoning_tokens
      title: ModelCost
      description: Token usage and cost for a single model.
    AgentRunStatusChangeData:
      properties:
        status:
          type: string
          enum:
          - running
          - paused
          title: Status
      additionalProperties: true
      type: object
      required:
      - status
      title: AgentRunStatusChangeData
    SessionStatus:
      properties:
        status:
          $ref: '#/components/schemas/TrajectoryStatus'
          description: Current lifecycle state of the session.
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if the session failed; null otherwise.
        error_code:
          anyOf:
          - $ref: '#/components/schemas/SessionErrorCode'
          - type: 'null'
          description: Machine-readable failure category if the session failed or timed out; null otherwise.
        outcome:
          anyOf:
          - $ref: '#/components/schemas/AnswerOutcome'
          - type: 'null'
          description: Agent's self-assessed task outcome, set with the final answer; null until then.
        steps:
          type: integer
          title: Steps
          description: Number of steps the agent has taken.
          default: 0
        usage_per_model:
          items:
            $ref: '#/components/schemas/ModelUsage'
          type: array
          title: Usage Per Model
          description: Per-model token usage. Empty until the agent calls a model.
        subagent_session_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Subagent Session Ids
          description: Session ids of any subagents this session spawned.
      type: object
      required:
      - status
      title: SessionStatus
      description: '``GET /api/v2/sessions/{id}/status`` response.'
    AgentErrorData:
      properties:
        error:
          type: string
          title: Error
        trace:
          type: string
          title: Trace
          default: ''
        info:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Info
      additionalProperties: true
      type: object
      required:
      - error
      title: AgentErrorData
    SessionErrorCode:
      type: string
      enum:
      - environment_error
      - no_answer
      - answer_validation
      - timeout
      - internal
      title: SessionErrorCode
      description: Machine-readable category of a terminal session failure.
    SessionChanges:
      properties:
        status:
          $ref: '#/components/schemas/TrajectoryStatus'
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
        finished_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Finished At
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        error_code:
          anyOf:
          - $ref: '#/components/schemas/SessionErrorCode'
          - type: 'null'
        new_events:
          items:
            $ref: '#/components/schemas/SessionEvent'
          type: array
          title: New Events
          default: []
        answer:
          anyOf:
          - type: string
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Answer
        outcome:
          anyOf:
          - $ref: '#/components/schemas/AnswerOutcome'
          - type: 'null'
        metrics:
          $ref: '#/components/schemas/Metrics'
      type: object
      required:
      - status
      title: SessionChanges
      description: Typed view of ``TrajectoryChanges`` for Agent API session endpoints.
    AnswerOutcome:
      type: string
      enum:
      - success
      - partial
      - infeasible
      - blocked
      title: AnswerOutcome
      description: Agent's self-assessment of how the task concluded, reported with the final answer.
    ObservationEvent:
      properties:
        kind:
          type: string
          const: observation_event
          title: Kind
          default: observation_event
        type:
          anyOf:
          - type: string
          - type: 'null'
          title: Type
          description: Environment that produced the observation, e.g. "web".
        text:
          anyOf:
          - type: string
          - type: 'null'
          title: Text
        image:
          anyOf:
          - $ref: '#/components/schemas/ImageContent'
          - type: 'null'
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Environment-specific snapshot, shaped by ``type``.
      type: object
      title: ObservationEvent
      description: 'What the agent perceived this step: optional text, screenshot and environment metadata.'
    RequestStartDispatchedEvent:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        type:
          type: string
          const: RequestStartDispatchedEvent
          title: Type
        data:
          $ref: '#/components/schemas/RequestStartDispatchedData'
      additionalProperties: true
      type: object
      required:
      - timestamp
      - type
      - data
      title: RequestStartDispatchedEvent
      description: The start request was dispatched to a runner.
    ToolDefinition:
      properties:
        name:
          type: string
          maxLength: 64
          minLength: 1
          title: Name
          description: 'Tool name advertised to the model. Format: letters, digits and underscores; must start with a letter or underscore; max 64 chars.'
        description:
          type: string
          minLength: 1
          title: Description
          description: What the tool does, when to use it, and what it returns. Shown to the model verbatim.
        input_schema:
          additionalProperties: true
          type: object
          title: Input Schema
          description: JSON Schema (object type) describing the tool call arguments.
      type: object
      required:
      - name
      - description
      title: ToolDefinition
      description: 'Contract for a tool executed by the API client, not by the agent runtime.


        The agent emits a tool call matching ``input_schema``, pauses, and resumes

        once the client sends back the corresponding tool result.'
    UserMessageEvent:
      properties:
        type:
          type: string
          const: user_message
          title: Type
          default: user_message
        message:
          type: string
          title: Message
          description: Message text sent to the agent.
        images:
          items:
            type: string
          type: array
          title: Images
          description: Optional images attached to the message, as base64 data URIs.
        caller_id:
          type: string
          title: Caller Id
          default: user
      type: object
      required:
      - message
      title: UserMessageEvent
      description: The user is sending a message to an active agent.
    AgentEvent:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        type:
          type: string
          const: AgentEvent
          title: Type
        data:
          oneOf:
          - $ref: '#/components/schemas/PolicyEvent'
          - $ref: '#/components/schemas/ToolResultEvent'
          - $ref: '#/components/schemas/AnswerEvent'
          - $ref: '#/components/schemas/ErrorEvent'
          - $ref: '#/components/schemas/MessageEvent'
          - $ref: '#/components/schemas/ObservationEvent'
          - $ref: '#/components/schemas/FlowEvent'
          title: Data
          discriminator:
            propertyName: kind
            mapping:
              answer_event: '#/components/schemas/AnswerEvent'
              error_event: '#/components/schemas/ErrorEvent'
              flow_event: '#/components/schemas/FlowEvent'
              message_event: '#/components/schemas/MessageEvent'
              observation_event: '#/components/schemas/ObservationEvent'
              policy_event: '#/components/schemas/PolicyEvent'
              tool_result: '#/components/schemas/ToolResultEvent'
      additionalProperties: true
      type: object
      required:
      - timestamp
      - type
      - data
      title: AgentEvent
      description: Event emitted by the agent loop itself; ``data`` is discriminated by ``kind``.
    RequestStartDispatchedData:
      properties:
        status:
          type: string
          title: Status
      additionalProperties: true
      type: object
      required:
      - status
      title: RequestStartDispatchedData
    LiveViewUrlData:
      properties:
        live_view_url:
          type: string
          title: Live View Url
      additionalProperties: true
      type: object
      required:
      - live_view_url
      title: LiveViewUrlData
    ActiveStateChangeData:
      properties:
        state:
          type: string
          enum:
          - running
          - idle
          - awaiting_tool_results
          title: State
        pending_tool_calls:
          anyOf:
          - items:
              $ref: '#/components/schemas/ToolRequest'
            type: array
          - type: 'null'
          title: Pending Tool Calls
      additionalProperties: true
      type: object
      required:
      - state
      title: ActiveStateChangeData
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer