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

# Get Conversation

> Fetch a conversation's execution, activity thread, usage, and sub-executions.

Returns the parent execution row, the full activity thread, aggregate cost / token usage, and every sub-execution's (execution, activity, usage) triple.

See the [Agent Gateway overview](/api-reference/v1/agents/gateway/overview) for the full conversation model.


## OpenAPI

````yaml GET /v1/agents/{agent_id}/gateway/conversations/{conversation_id}
openapi: 3.1.0
info:
  title: xpander.ai API Service
  description: |2-

        The xpander.ai API Service provides a unified REST API for managing AI agents,
        executing tasks, managing knowledge bases, and integrating with external systems.
        
        Features:
        - Agent Management: Create, update, deploy, and delete AI agents
        - Task Execution: Invoke agents with support for sync, async, and streaming modes
        - Knowledge Bases: Manage knowledge bases and documents for RAG workflows
        - Tools: Discover, connect, and attach tools (connectors, custom functions, MCP servers, sub-agents, workflows) to agents and workflows
        - MCP Integration: Model Context Protocol support for standardized AI interactions
        
        Authentication: All endpoints require authentication via either an API key (`x-api-key`) or an OAuth2 JWT (`Authorization: Bearer <jwt>`).
        
  version: '0.001'
servers:
  - url: https://api.xpander.ai
security: []
paths:
  /v1/agents/{agent_id}/gateway/conversations/{conversation_id}:
    get:
      tags:
        - API v1
        - Agents
        - Agent Gateway
      summary: Get Conversation
      description: >-
        Return the parent execution, activity thread, aggregate cost / token
        usage, and every sub-execution's (execution, activity, usage) triple.
      operationId: >-
        Get_Conversation_v1_agents__agent_id__gateway_conversations__conversation_id__get
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            title: Agent Id
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
            title: Conversation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    ConversationResponse:
      properties:
        conversation_id:
          type: string
          title: Conversation Id
        execution:
          anyOf:
            - $ref: '#/components/schemas/AgentExecution'
            - type: 'null'
          description: >-
            Parent gateway execution row (status, result, sub_executions,
            deep_planning, …).
        activity:
          anyOf:
            - $ref: '#/components/schemas/AgentActivityThread'
            - type: 'null'
          description: Ordered message list (user, agent, tool calls, reasoning, …).
        usage:
          anyOf:
            - $ref: '#/components/schemas/ConversationUsage'
            - type: 'null'
          description: >-
            Aggregate cost + token usage over parent + every sub-execution.
            Best-effort.
        sub_executions:
          items:
            $ref: '#/components/schemas/SubExecutionResponse'
          type: array
          title: Sub Executions
          description: >-
            Triple-shape entry for every sub-execution spawned by this
            conversation.
        feedbacks:
          items:
            $ref: '#/components/schemas/MessageFeedbackItem'
          type: array
          title: Feedbacks
          description: Per-message feedback rows recorded against the parent execution.
      type: object
      required:
        - conversation_id
      title: ConversationResponse
      description: >-
        Combined view of one chat conversation.


        `conversation_id` is the parent gateway execution id, which is also the

        activity-thread id. `execution`, `activity`, and `usage` can each be

        independently `None` when the upstream is unavailable — the route
        returns

        404 only when BOTH `execution` AND `activity` are missing.


        `usage` at this root level is aggregated across the parent execution

        AND every entry in `sub_executions` (single upstream call to the

        `llm_usage:aggregate` endpoint). Per-sub usage is mirrored on each

        `SubExecutionResponse.usage` so clients don't have to fan-out.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentExecution:
      properties:
        id:
          type: string
          title: Id
        agent_id:
          type: string
          title: Agent Id
        organization_id:
          type: string
          title: Organization Id
        input:
          $ref: '#/components/schemas/AgentExecutionInput-Output'
        status:
          anyOf:
            - $ref: >-
                #/components/schemas/xpander_dev_utils__models__executions__AgentExecutionStatus
            - type: 'null'
          default: pending
        internal_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Internal Status
        last_executed_node_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Executed Node Id
        agent_version:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Version
        created_at:
          type: string
          format: date-time
          title: Created At
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
        paused_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Paused At
        finished_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Finished At
        result:
          anyOf:
            - type: string
            - type: 'null'
          title: Result
        parent_execution:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Execution
        sub_executions:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Sub Executions
          default: []
        finished_sub_executions:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Finished Sub Executions
          default: []
        should_update_parent:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Should Update Parent
          default: false
        is_manually_stopped:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Manually Stopped
          default: false
        is_background:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Background
          default: false
        payload_extension:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Payload Extension
        hitl_request:
          anyOf:
            - $ref: '#/components/schemas/HumanInTheLoopRequest'
            - type: 'null'
        pending_eca_request:
          anyOf:
            - $ref: '#/components/schemas/PendingECARequest'
            - type: 'null'
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
        worker_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Worker Id
        additional_context:
          anyOf:
            - type: string
            - type: 'null'
          title: Additional Context
        instructions_override:
          anyOf:
            - type: string
            - type: 'null'
          title: Instructions Override
        expected_output:
          anyOf:
            - type: string
            - type: 'null'
          title: Expected Output
        test_run_node_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Test Run Node Id
        is_orchestration:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Orchestration
          default: false
        is_gateway:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Gateway
          default: false
        output_format:
          anyOf:
            - $ref: '#/components/schemas/OutputFormat'
            - type: 'null'
          default: text
        voice_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Voice Id
        output_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Output Schema
        events_streaming:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Events Streaming
          default: false
        used_mutating_tools:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Used Mutating Tools
          default: false
        is_continuous:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Continuous
          default: false
        mcp_servers:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Mcp Servers
          default: []
        triggering_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Triggering Agent Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        think_mode:
          anyOf:
            - $ref: '#/components/schemas/ThinkMode'
            - type: 'null'
          default: default
        disable_attachment_injection:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Disable Attachment Injection
          default: false
        deep_planning:
          anyOf:
            - $ref: '#/components/schemas/DeepPlanning'
            - type: 'null'
        execution_attempts:
          anyOf:
            - type: integer
            - type: 'null'
          title: Execution Attempts
          default: 1
        user_tokens:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: User Tokens
        user_oidc_token:
          anyOf:
            - type: string
            - type: 'null'
          title: User Oidc Token
        return_metrics:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Return Metrics
          default: false
        tokens:
          anyOf:
            - $ref: '#/components/schemas/LLMTokens'
            - type: 'null'
        llm_model_provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Llm Model Provider
          description: >-
            Snapshot of the LLM provider used for this execution (request
            override or agent default at run time).
        llm_model_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Llm Model Name
          description: >-
            Snapshot of the LLM model name used for this execution (request
            override or agent default at run time).
        llm_reasoning_effort:
          anyOf:
            - $ref: '#/components/schemas/LLMReasoningEffort'
            - type: 'null'
          description: >-
            Snapshot of the reasoning effort applied during this execution, when
            supported by the model.
      type: object
      required:
        - id
        - agent_id
        - organization_id
        - input
        - created_at
      title: AgentExecution
    AgentActivityThread:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        messages:
          items:
            anyOf:
              - $ref: '#/components/schemas/AgentActivityThreadMessage'
              - $ref: '#/components/schemas/AgentActivityThreadToolCall'
              - $ref: '#/components/schemas/AgentActivityThreadReasoning'
              - $ref: '#/components/schemas/AgentActivityThreadSubAgentTrigger'
              - $ref: '#/components/schemas/AgentActivityThreadAuth'
              - $ref: '#/components/schemas/AgentActivityThreadPlanUpdate'
              - $ref: >-
                  #/components/schemas/AgentActivityThreadTaskCompactizationEvent
              - $ref: '#/components/schemas/AgentActivityThreadGatewayCreateExecution'
              - $ref: '#/components/schemas/AgentActivityThreadGatewayAskExecution'
              - $ref: '#/components/schemas/AgentActivityThreadGatewayStopExecution'
              - $ref: >-
                  #/components/schemas/AgentActivityThreadGatewayContinueExecution
              - $ref: >-
                  #/components/schemas/AgentActivityThreadGatewayGetExecutionsResult
              - $ref: >-
                  #/components/schemas/AgentActivityThreadGatewayAskUserQuestions
              - $ref: >-
                  #/components/schemas/AgentActivityThreadAskUserQuestionsAnswers
              - $ref: '#/components/schemas/AgentActivityThreadGatewaySuggestTool'
              - $ref: '#/components/schemas/AgentActivityThreadToolSuggestionResolved'
              - $ref: '#/components/schemas/AgentActivityThreadGatewayInviteMember'
              - $ref: '#/components/schemas/AgentActivityThreadInviteMemberResolved'
              - $ref: '#/components/schemas/AgentActivityThreadGatewayAskForSecret'
              - $ref: '#/components/schemas/AgentActivityThreadAskForSecretResolved'
              - $ref: '#/components/schemas/AgentActivityThreadLiveSurface'
          type: array
          title: Messages
        user:
          anyOf:
            - $ref: '#/components/schemas/User-Output'
            - type: 'null'
        context_status:
          anyOf:
            - $ref: '#/components/schemas/ContextStatus'
            - type: 'null'
        state:
          $ref: '#/components/schemas/ConversationState'
          default: regular
      type: object
      required:
        - id
        - created_at
        - messages
      title: AgentActivityThread
    ConversationUsage:
      properties:
        cost:
          type: number
          title: Cost
          description: >-
            Estimated USD cost for non-BYOK executions in this thread, rounded
            to 5 decimals. Excludes BYOK executions (the customer is billed by
            their own LLM provider for those).
          default: 0
        is_byok:
          type: boolean
          title: Is Byok
          description: True if any execution in the thread used BYOK credentials.
          default: false
        actions:
          type: integer
          title: Actions
          description: Total number of agent actions (tool calls) across the thread.
          default: 0
        ai_model:
          anyOf:
            - type: string
            - type: 'null'
          title: Ai Model
          description: >-
            Dominant LLM model id used in the thread (the model that produced
            the most tokens). `None` when no executions have been recorded yet.
        tokens:
          $ref: '#/components/schemas/ConversationTokens'
      type: object
      title: ConversationUsage
      description: |-
        Cost + token usage for a conversation (or a single sub-execution).

        Sourced from the same monitoring rollup the api service exposes at
        `/v1/tasks/{task_id}/llm_usage`. Flow:

          chat-backend  →  agent-controller (in-process call)
                        →  deployment-manager (`agents_activity_proxy`)
                        →  agents service (`/{agent_id}/activity/threads/llm_usage:aggregate`)
                        →  MongoDB monitoring docs + LLM tier table

        Returned with the conversation as a convenience so the UI doesn't
        have to issue a second roundtrip per render.
    SubExecutionResponse:
      properties:
        conversation_id:
          type: string
          title: Conversation Id
          description: The sub-execution id (== its activity thread id).
        execution:
          anyOf:
            - $ref: '#/components/schemas/AgentExecution'
            - type: 'null'
          description: Child execution row (status, result, ai_model, ...).
        activity:
          anyOf:
            - $ref: '#/components/schemas/AgentActivityThread'
            - type: 'null'
          description: >-
            Child execution's own activity thread (user, agent, tool calls,
            ...).
        usage:
          anyOf:
            - $ref: '#/components/schemas/ConversationUsage'
            - type: 'null'
          description: >-
            Usage for this sub-execution alone. Best-effort; None when upstream
            fails.
        feedbacks:
          items:
            $ref: '#/components/schemas/MessageFeedbackItem'
          type: array
          title: Feedbacks
          description: Per-message feedback rows recorded against this sub-execution.
      type: object
      required:
        - conversation_id
      title: SubExecutionResponse
      description: >-
        One sub-execution's `(execution, activity, usage)` triple.


        Same shape as `ConversationResponse` minus the recursive
        `sub_executions`

        list — sub-executions don't currently spawn their own sub-executions in

        the chat-backend surface, so we keep the depth at one level.
    MessageFeedbackItem:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        conversation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversation Id
          description: Task/thread id this feedback belongs to.
        message_id:
          type: string
          title: Message Id
          description: The feedbacked activity message id.
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        is_positive:
          type: boolean
          title: Is Positive
          description: True for thumbs-up, false for thumbs-down.
        comment:
          anyOf:
            - type: string
            - type: 'null'
          title: Comment
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
        updated_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Updated At
      type: object
      required:
        - message_id
        - is_positive
      title: MessageFeedbackItem
      description: >-
        A persisted thumbs up/down feedback row for one message in a
        conversation.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    AgentExecutionInput-Output:
      properties:
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
          default: ''
        files:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Files
          default: []
        user:
          anyOf:
            - $ref: '#/components/schemas/User-Output'
            - type: 'null'
      type: object
      title: AgentExecutionInput
    xpander_dev_utils__models__executions__AgentExecutionStatus:
      type: string
      enum:
        - pending
        - executing
        - paused
        - error
        - failed
        - completed
        - stopped
      title: AgentExecutionStatus
    HumanInTheLoopRequest:
      properties:
        wait_node_id:
          type: string
          title: Wait Node Id
      type: object
      required:
        - wait_node_id
      title: HumanInTheLoopRequest
      description: |-
        Model representing human-in-the-loop approval records for tasks.

        Attributes:
            wait_node_id (str): The id of the node that triggered this HITL.
    PendingECARequest:
      properties:
        connector_name:
          type: string
          title: Connector Name
        auth_url:
          type: string
          title: Auth Url
      type: object
      required:
        - connector_name
        - auth_url
      title: PendingECARequest
    OutputFormat:
      type: string
      enum:
        - text
        - markdown
        - json
        - voice
      title: OutputFormat
    ThinkMode:
      type: string
      enum:
        - default
        - harder
      title: ThinkMode
    DeepPlanning:
      properties:
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enabled
          default: false
        enforce:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enforce
          default: false
        started:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Started
          default: false
        question_raised:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Question Raised
          default: false
        tasks:
          anyOf:
            - items:
                $ref: '#/components/schemas/DeepPlanningItem'
              type: array
            - type: 'null'
          title: Tasks
          default: []
      type: object
      title: DeepPlanning
    LLMTokens:
      properties:
        completion_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Completion Tokens
          default: 0
        prompt_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Prompt Tokens
          default: 0
        total_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Tokens
          default: 0
      type: object
      title: LLMTokens
    LLMReasoningEffort:
      type: string
      enum:
        - low
        - medium
        - high
        - xhigh
      title: LLMReasoningEffort
    AgentActivityThreadMessage:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        role:
          type: string
          enum:
            - user
            - agent
          title: Role
        content:
          $ref: '#/components/schemas/AgentActivityThreadMessageContent'
        sub_execution_result:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Sub Execution Result
          default: false
        is_steering:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Steering
          default: false
        user:
          anyOf:
            - $ref: '#/components/schemas/User-Output'
            - type: 'null'
      type: object
      required:
        - id
        - created_at
        - role
        - content
      title: AgentActivityThreadMessage
    AgentActivityThreadToolCall:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        tool_name:
          type: string
          title: Tool Name
        operation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Operation Id
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        payload:
          title: Payload
        is_error:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Error
          default: false
        reasoning:
          anyOf:
            - $ref: '#/components/schemas/ToolCallRequestReasoning'
            - type: 'null'
        result:
          anyOf:
            - {}
            - type: 'null'
          title: Result
        plan_task_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Plan Task Id
      type: object
      required:
        - id
        - created_at
        - tool_name
        - payload
      title: AgentActivityThreadToolCall
    AgentActivityThreadReasoning:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        type:
          $ref: '#/components/schemas/AgentActivityThreadReasoningType'
        title:
          type: string
          title: Title
        confidence:
          type: number
          title: Confidence
        thought:
          anyOf:
            - type: string
            - type: 'null'
          title: Thought
        action:
          anyOf:
            - type: string
            - type: 'null'
          title: Action
        result:
          anyOf:
            - type: string
            - type: 'null'
          title: Result
        analysis:
          anyOf:
            - type: string
            - type: 'null'
          title: Analysis
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        plan_task_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Plan Task Id
      type: object
      required:
        - id
        - created_at
        - type
        - title
        - confidence
      title: AgentActivityThreadReasoning
    AgentActivityThreadSubAgentTrigger:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        agent_id:
          type: string
          title: Agent Id
        query:
          anyOf:
            - type: string
            - type: 'null'
          title: Query
        task_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Task Id
        result:
          anyOf:
            - type: string
            - type: 'null'
          title: Result
        files:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Files
          default: []
        reasoning:
          $ref: '#/components/schemas/ToolCallRequestReasoning'
        plan_task_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Plan Task Id
      type: object
      required:
        - id
        - created_at
        - agent_id
        - reasoning
      title: AgentActivityThreadSubAgentTrigger
    AgentActivityThreadAuth:
      properties:
        type:
          $ref: '#/components/schemas/MCPOAuthResponseType'
        data:
          anyOf:
            - $ref: '#/components/schemas/MCPOAuthGetTokenTokenReadyResponse'
            - $ref: '#/components/schemas/MCPOAuthGetTokenLoginRequiredResponse'
            - $ref: '#/components/schemas/MCPOAuthGetTokenGenericResponse'
          title: Data
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - type
        - data
        - id
        - created_at
      title: AgentActivityThreadAuth
    AgentActivityThreadPlanUpdate:
      properties:
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enabled
          default: false
        enforce:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enforce
          default: false
        started:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Started
          default: false
        question_raised:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Question Raised
          default: false
        tasks:
          anyOf:
            - items:
                $ref: '#/components/schemas/DeepPlanningItem'
              type: array
            - type: 'null'
          title: Tasks
          default: []
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
      type: object
      required:
        - id
        - created_at
      title: AgentActivityThreadPlanUpdate
    AgentActivityThreadTaskCompactizationEvent:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        type:
          type: string
          enum:
            - retry
            - summarization
            - compaction_started
            - compaction_progress
            - manual_compaction
            - emergency_compaction
            - pre_retry_compaction
            - compaction_error
          title: Type
        data:
          anyOf:
            - $ref: '#/components/schemas/TaskCompactizationOutput'
            - $ref: '#/components/schemas/TaskCompactizationRetryEvent'
            - $ref: '#/components/schemas/TaskCompactizationStarted'
            - $ref: '#/components/schemas/TaskCompactizationProgress'
            - $ref: '#/components/schemas/TaskCompactizationError'
          title: Data
      type: object
      required:
        - id
        - created_at
        - type
        - data
      title: AgentActivityThreadTaskCompactizationEvent
    AgentActivityThreadGatewayCreateExecution:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        reasoning:
          type: string
          title: Reasoning
        title:
          type: string
          title: Title
          default: ''
        description:
          type: string
          title: Description
          default: ''
        action:
          type: string
          const: create_execution
          title: Action
          default: create_execution
        created_execution_id:
          type: string
          title: Created Execution Id
        query:
          type: string
          title: Query
          default: ''
        is_async:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Async
          default: false
        ack_message:
          type: string
          title: Ack Message
          default: ''
        target_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Target Agent Id
        target_agent_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Target Agent Name
      type: object
      required:
        - id
        - created_at
        - reasoning
        - created_execution_id
      title: AgentActivityThreadGatewayCreateExecution
    AgentActivityThreadGatewayAskExecution:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        reasoning:
          type: string
          title: Reasoning
        title:
          type: string
          title: Title
          default: ''
        description:
          type: string
          title: Description
          default: ''
        action:
          type: string
          const: ask_execution
          title: Action
          default: ask_execution
        created_execution_id:
          type: string
          title: Created Execution Id
        new_input:
          type: string
          title: New Input
        rejected:
          anyOf:
            - type: string
            - type: 'null'
          title: Rejected
      type: object
      required:
        - id
        - created_at
        - reasoning
        - created_execution_id
        - new_input
      title: AgentActivityThreadGatewayAskExecution
    AgentActivityThreadGatewayStopExecution:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        reasoning:
          type: string
          title: Reasoning
        title:
          type: string
          title: Title
          default: ''
        description:
          type: string
          title: Description
          default: ''
        action:
          type: string
          const: stop_execution
          title: Action
          default: stop_execution
        created_execution_id:
          type: string
          title: Created Execution Id
      type: object
      required:
        - id
        - created_at
        - reasoning
        - created_execution_id
      title: AgentActivityThreadGatewayStopExecution
    AgentActivityThreadGatewayContinueExecution:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        reasoning:
          type: string
          title: Reasoning
        title:
          type: string
          title: Title
          default: ''
        description:
          type: string
          title: Description
          default: ''
        action:
          type: string
          const: continue_execution
          title: Action
          default: continue_execution
        created_execution_id:
          type: string
          title: Created Execution Id
        rejected:
          anyOf:
            - type: string
            - type: 'null'
          title: Rejected
      type: object
      required:
        - id
        - created_at
        - reasoning
        - created_execution_id
      title: AgentActivityThreadGatewayContinueExecution
    AgentActivityThreadGatewayGetExecutionsResult:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        reasoning:
          type: string
          title: Reasoning
        title:
          type: string
          title: Title
          default: ''
        description:
          type: string
          title: Description
          default: ''
        action:
          type: string
          const: get_executions_result
          title: Action
          default: get_executions_result
        executions:
          items:
            $ref: >-
              #/components/schemas/AgentActivityThreadGatewayExecutionResultEntry
          type: array
          title: Executions
          default: []
      type: object
      required:
        - id
        - created_at
        - reasoning
      title: AgentActivityThreadGatewayGetExecutionsResult
    AgentActivityThreadGatewayAskUserQuestions:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        reasoning:
          type: string
          title: Reasoning
        title:
          type: string
          title: Title
          default: ''
        description:
          type: string
          title: Description
          default: ''
        action:
          type: string
          const: ask_user_questions
          title: Action
          default: ask_user_questions
        questions:
          items:
            $ref: '#/components/schemas/GatewayQuestion'
          type: array
          title: Questions
          default: []
      type: object
      required:
        - id
        - created_at
        - reasoning
      title: AgentActivityThreadGatewayAskUserQuestions
    AgentActivityThreadAskUserQuestionsAnswers:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        decision_id:
          type: string
          title: Decision Id
        answers:
          items:
            $ref: '#/components/schemas/GatewayAnswerItem'
          type: array
          title: Answers
          default: []
        user:
          anyOf:
            - $ref: '#/components/schemas/User-Output'
            - type: 'null'
      type: object
      required:
        - id
        - created_at
        - decision_id
      title: AgentActivityThreadAskUserQuestionsAnswers
      description: >-
        User-submitted answers to a prior ask_user_questions card.


        Persisted as its own activity entry (links to the question via

        `decision_id`) and replayed into the gateway LLM context as a user
        message.
    AgentActivityThreadGatewaySuggestTool:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        reasoning:
          type: string
          title: Reasoning
        title:
          type: string
          title: Title
          default: ''
        description:
          type: string
          title: Description
          default: ''
        action:
          type: string
          const: suggest_tool
          title: Action
          default: suggest_tool
        suggestions:
          items:
            $ref: '#/components/schemas/GatewaySuggestedTool'
          type: array
          title: Suggestions
          default: []
        allow_custom_mcp:
          type: boolean
          title: Allow Custom Mcp
          default: false
      type: object
      required:
        - id
        - created_at
        - reasoning
      title: AgentActivityThreadGatewaySuggestTool
    AgentActivityThreadToolSuggestionResolved:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        decision_id:
          type: string
          title: Decision Id
        choice:
          $ref: '#/components/schemas/ToolSuggestionChoice'
        tool_name:
          type: string
          title: Tool Name
          default: ''
        user:
          anyOf:
            - $ref: '#/components/schemas/User-Output'
            - type: 'null'
      type: object
      required:
        - id
        - created_at
        - decision_id
        - choice
      title: AgentActivityThreadToolSuggestionResolved
      description: >-
        The user's resolved choice for a prior suggest_tool card.


        Persisted as its own activity entry (links via `decision_id`) so the
        card

        locks on reload; the attach itself happens in the chat-backend route.
    AgentActivityThreadGatewayInviteMember:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        reasoning:
          type: string
          title: Reasoning
        title:
          type: string
          title: Title
          default: ''
        description:
          type: string
          title: Description
          default: ''
        action:
          type: string
          const: invite_member
          title: Action
          default: invite_member
        email:
          type: string
          title: Email
          default: ''
        role:
          $ref: '#/components/schemas/GatewayInviteRole'
          default: member
        editable:
          type: boolean
          title: Editable
          default: true
      type: object
      required:
        - id
        - created_at
        - reasoning
      title: AgentActivityThreadGatewayInviteMember
    AgentActivityThreadInviteMemberResolved:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        decision_id:
          type: string
          title: Decision Id
        email:
          type: string
          title: Email
        role:
          $ref: '#/components/schemas/GatewayInviteRole'
          default: member
        user:
          anyOf:
            - $ref: '#/components/schemas/User-Output'
            - type: 'null'
      type: object
      required:
        - id
        - created_at
        - decision_id
        - email
      title: AgentActivityThreadInviteMemberResolved
      description: >-
        The user's resolved confirmation for a prior invite_member card.


        Persisted as its own activity entry (links via `decision_id`) so the
        card

        locks on reload; the invite itself happens in the chat-backend route.
    AgentActivityThreadGatewayAskForSecret:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        reasoning:
          type: string
          title: Reasoning
        title:
          type: string
          title: Title
          default: ''
        description:
          type: string
          title: Description
          default: ''
        action:
          type: string
          const: ask_for_secret
          title: Action
          default: ask_for_secret
        secrets:
          items:
            $ref: '#/components/schemas/RequiredSecret'
          type: array
          title: Secrets
          default: []
      type: object
      required:
        - id
        - created_at
        - reasoning
      title: AgentActivityThreadGatewayAskForSecret
    AgentActivityThreadAskForSecretResolved:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        decision_id:
          type: string
          title: Decision Id
        names:
          items:
            type: string
          type: array
          title: Names
          default: []
        user:
          anyOf:
            - $ref: '#/components/schemas/User-Output'
            - type: 'null'
      type: object
      required:
        - id
        - created_at
        - decision_id
      title: AgentActivityThreadAskForSecretResolved
      description: >-
        The user's resolution of a prior ask_for_secret card (names only, no
        values).


        Persisted as its own activity entry (links via `decision_id`) so the
        card

        locks on reload; the save itself happens in the chat-backend route.
    AgentActivityThreadLiveSurface:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        surface_id:
          type: string
          title: Surface Id
        title:
          type: string
          title: Title
          default: ''
        surface_kind:
          type: string
          title: Surface Kind
          default: manifest
        cdn_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Cdn Url
        manifest:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Manifest
      type: object
      required:
        - id
        - created_at
        - surface_id
      title: AgentActivityThreadLiveSurface
      description: >-
        A Live Surface the agent generated; rendered as an in-chat preview
        (one-liner teaser) the user

        opens full screen. Persisted on the thread so it survives the closed
        async stream + reload, and so

        multiple surfaces in one conversation each get their own preview.
    User-Output:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
        email:
          type: string
          title: Email
        additional_attributes:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Additional Attributes
        role:
          anyOf:
            - type: string
            - type: 'null'
          title: Role
          default: member
        is_super_admin:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Super Admin
          default: false
        timezone:
          anyOf:
            - type: string
            - type: 'null'
          title: Timezone
        display_name:
          type: string
          title: Display Name
          readOnly: true
      type: object
      required:
        - email
        - display_name
      title: User
      description: |-
        Represents the details of a user.

        Attributes:
            id (Optional[str]): The unique identifier of the user. Defaults to None.
            first_name (Optional[str]): The first name of the user. Defaults to None.
            last_name (Optional[str]): The last name of the user. Defaults to None.
            email (str): The email address of the user. This field is required.
            additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service.
            role (Optional[str]): The user's role in the organization. Defaults to "member".
            is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False.
            timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None.
    ContextStatus:
      properties:
        estimated_tokens:
          type: integer
          title: Estimated Tokens
          description: >-
            Rough token count of the current message list (post-Layer-1
            microcompaction).
        context_window:
          type: integer
          title: Context Window
          description: Model context window size in tokens.
        percent:
          type: number
          title: Percent
          description: estimated_tokens / context_window * 100, clamped to [0, 100].
        auto_compact_threshold:
          type: integer
          title: Auto Compact Threshold
          description: Token level at which Layer 2 auto-compaction fires.
        emergency_threshold:
          type: integer
          title: Emergency Threshold
          description: Token level at which the emergency safety net (88%) fires.
        compacting:
          type: boolean
          title: Compacting
          description: True while a Layer 2 compaction is in flight on the current turn.
          default: false
      type: object
      required:
        - estimated_tokens
        - context_window
        - percent
        - auto_compact_threshold
        - emergency_threshold
      title: ContextStatus
      description: Per-turn snapshot of the LLM context window for the chat UI indicator.
    ConversationState:
      type: string
      enum:
        - regular
        - agent_building
        - agent_updating
      title: ConversationState
      description: >-
        Lifecycle phase of a gateway conversation; drives UI affordance +
        gateway model selection.
    ConversationTokens:
      properties:
        input:
          type: integer
          title: Input
          default: 0
        output:
          type: integer
          title: Output
          default: 0
        total:
          type: integer
          title: Total
          default: 0
      type: object
      title: ConversationTokens
      description: Aggregated token counts across every execution in the thread.
    DeepPlanningItem:
      properties:
        id:
          type: string
          title: Id
        title:
          type: string
          title: Title
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        input:
          anyOf:
            - {}
            - type: 'null'
          title: Input
        output:
          anyOf:
            - {}
            - type: 'null'
          title: Output
        tool_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Name
        completed:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Completed
          default: false
      type: object
      required:
        - id
        - title
      title: DeepPlanningItem
    AgentActivityThreadMessageContent:
      properties:
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
        files:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Files
          default: []
      type: object
      title: AgentActivityThreadMessageContent
    ToolCallRequestReasoning:
      properties:
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
      type: object
      title: ToolCallRequestReasoning
    AgentActivityThreadReasoningType:
      type: string
      enum:
        - think
        - analyze
      title: AgentActivityThreadReasoningType
    MCPOAuthResponseType:
      type: string
      enum:
        - not_supported
        - login_required
        - token_issue
        - token_ready
      title: MCPOAuthResponseType
    MCPOAuthGetTokenTokenReadyResponse:
      properties:
        access_token:
          type: string
          title: Access Token
      type: object
      required:
        - access_token
      title: MCPOAuthGetTokenTokenReadyResponse
    MCPOAuthGetTokenLoginRequiredResponse:
      properties:
        url:
          type: string
          title: Url
        server_url:
          type: string
          title: Server Url
        server_name:
          type: string
          title: Server Name
      type: object
      required:
        - url
        - server_url
        - server_name
      title: MCPOAuthGetTokenLoginRequiredResponse
    MCPOAuthGetTokenGenericResponse:
      properties:
        message:
          type: string
          title: Message
      type: object
      required:
        - message
      title: MCPOAuthGetTokenGenericResponse
    TaskCompactizationOutput:
      properties:
        new_task_prompt:
          type: string
          minLength: 1
          title: New Task Prompt
          description: >-
            A continuation prompt that seamlessly continues the running
            execution. This is NOT a new task - it's the next message in an
            ongoing conversation. The prompt must:

            1. Resume from where the execution left off (do NOT repeat completed
            work)

            2. Focus on completing ALL remaining uncompleted tasks

            3. Include specific instructions to mark each task as completed
            after finishing it

            4. Be written as if you're continuing mid-conversation, not starting
            fresh

            5. Reference the current state and what still needs to be done

            Example: 'Continuing from where we left off, we still need to
            complete tasks X, Y, and Z. Let's proceed with task X first, then
            mark it complete using the appropriate tool.'
        task_context:
          type: string
          minLength: 1
          title: Task Context
          description: >
            Comprehensive context for continuing the execution. This context
            will be injected into the agent's system prompt to maintain
            execution continuity.


            REQUIRED FORMAT (use these exact headings, in this order):

            1) ORIGINAL USER REQUEST

            - Verbatim user_input text and any file references.


            2) AGENT INSTRUCTIONS IN EFFECT

            - General description from agent instructions.

            - Role instructions (bullet list).

            - Goals (bullet list).

            - Any constraints or special requirements.


            3) EXECUTION SUMMARY

            - What actions were taken (facts only, no speculation).

            - What outputs were produced (facts only).


            4) CURRENT STATE AND ARTIFACTS

            - All created artifacts with their identifiers, paths, URLs, or
            references.

            - Current state of variables, decisions, configurations, and
            assumptions.

            - Active session or database state if relevant.


            5) MESSAGES AND KEY EVIDENCE

            - Compact chronological summary of the conversation flow.

            - Up to 5 verbatim quotes (max 25 words each) capturing critical
            details.


            6) TOOL CALLS AND OBSERVATIONS

            - For each tool call: tool name/id, purpose, key inputs, key
            outputs, errors.

            - Include plan tool calls (create/get/complete) if they occurred.

            - If no tools used: 'No tool calls were made.'


            7) COMPLETED VS UNCOMPLETED TASKS

            - Completed: List with task IDs and titles that are done.

            - Uncompleted: List each task ID, title, and specific reason it's
            incomplete.

            - CRITICAL: All uncompleted tasks MUST be finished in the
            continuation.


            8) OPEN QUESTIONS AND UNKNOWNS

            - Missing information needed to complete remaining tasks.

            - Blockers or dependencies preventing progress.

            - If none: 'No open questions.'


            9) NEXT ACTIONS TO COMPLETE ALL TASKS

            - Ordered list of specific actions to complete each uncompleted
            task.

            - Each action should reference the task ID it completes.

            - Final action must be to mark all tasks as completed using the plan
            tools.


            ACCURACY REQUIREMENTS:

            - Do NOT invent details. Use 'Unknown' if information is missing.

            - Preserve exact names, IDs, numbers, file paths, and user wording.

            - Task completion status must match reality - no implied completion.

            - Focus on actionable, specific continuation steps.
      type: object
      required:
        - new_task_prompt
        - task_context
      title: TaskCompactizationOutput
    TaskCompactizationRetryEvent:
      properties:
        is_retry:
          type: boolean
          title: Is Retry
      type: object
      required:
        - is_retry
      title: TaskCompactizationRetryEvent
    TaskCompactizationStarted:
      properties:
        trigger:
          type: string
          enum:
            - auto
            - manual
            - emergency
            - pre_retry
          title: Trigger
        estimated_tokens:
          type: integer
          title: Estimated Tokens
        message_count:
          type: integer
          title: Message Count
        threshold:
          type: integer
          title: Threshold
        attempt:
          type: integer
          title: Attempt
          default: 1
        focus:
          anyOf:
            - type: string
            - type: 'null'
          title: Focus
      type: object
      required:
        - trigger
        - estimated_tokens
        - message_count
        - threshold
      title: TaskCompactizationStarted
      description: Emitted when a compaction attempt begins.
    TaskCompactizationProgress:
      properties:
        trigger:
          type: string
          enum:
            - auto
            - manual
            - emergency
            - pre_retry
          title: Trigger
        attempt:
          type: integer
          title: Attempt
          default: 1
        percent:
          type: number
          title: Percent
          default: 0
        label:
          type: string
          title: Label
          default: Compacting context
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      required:
        - trigger
      title: TaskCompactizationProgress
      description: |-
        Customer-facing progress update emitted during a running compaction.

        Designed for direct rendering: the UI should only need ``percent``,
        ``label`` and the optional ``detail`` line. Internal phase / timing /
        streaming metrics are intentionally NOT included in the wire payload.
    TaskCompactizationError:
      properties:
        trigger:
          type: string
          enum:
            - auto
            - manual
            - emergency
            - pre_retry
          title: Trigger
        error:
          type: string
          title: Error
        attempt:
          type: integer
          title: Attempt
          default: 1
      type: object
      required:
        - trigger
        - error
      title: TaskCompactizationError
      description: Emitted when a compaction attempt fails.
    AgentActivityThreadGatewayExecutionResultEntry:
      properties:
        created_execution_id:
          type: string
          title: Created Execution Id
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
        result:
          anyOf:
            - type: string
            - type: 'null'
          title: Result
      type: object
      required:
        - created_execution_id
      title: AgentActivityThreadGatewayExecutionResultEntry
    GatewayQuestion:
      properties:
        id:
          type: string
          title: Id
          description: Stable id used to correlate the user's answer.
        text:
          type: string
          title: Text
          description: The question itself, in the user's language.
        header:
          type: string
          title: Header
          description: Short chip/label for the question card.
          default: ''
        options:
          items:
            $ref: '#/components/schemas/GatewayQuestionOption'
          type: array
          title: Options
        allow_free_text:
          type: boolean
          title: Allow Free Text
          description: True → the user may type a custom answer (free-text or 'Other').
          default: false
        multi_select:
          type: boolean
          title: Multi Select
          description: True → more than one option may be selected.
          default: false
      type: object
      required:
        - id
        - text
      title: GatewayQuestion
      description: A single question surfaced to the user.
    GatewayAnswerItem:
      properties:
        question_id:
          type: string
          title: Question Id
        question_text:
          type: string
          title: Question Text
          default: ''
        header:
          type: string
          title: Header
          default: ''
        selected_options:
          items:
            $ref: '#/components/schemas/GatewayQuestionOption'
          type: array
          title: Selected Options
        free_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Free Text
      type: object
      required:
        - question_id
      title: GatewayAnswerItem
      description: One resolved answer, denormalized for activity-log rendering.
    GatewaySuggestedTool:
      properties:
        kind:
          $ref: '#/components/schemas/GatewayToolKind'
        name:
          type: string
          title: Name
          description: User-facing tool / connector name.
        description:
          type: string
          title: Description
          default: ''
        logo:
          anyOf:
            - type: string
            - type: 'null'
          title: Logo
        connector_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Connector Id
        using_built_in_auth:
          type: boolean
          title: Using Built In Auth
          default: false
        connections:
          items:
            $ref: '#/components/schemas/GatewayConnectorConnection'
          type: array
          title: Connections
        mcp_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Id
        skill_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Skill Name
        target_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Target Id
        transport:
          anyOf:
            - type: string
            - type: 'null'
          title: Transport
        auth_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Auth Type
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
      type: object
      required:
        - kind
        - name
      title: GatewaySuggestedTool
      description: One candidate tool surfaced in a SuggestTool card.
    ToolSuggestionChoice:
      properties:
        kind:
          $ref: '#/components/schemas/GatewayToolKind'
        connector_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Connector Id
        connection_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Connection Id
        security:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Security
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        access_scope:
          anyOf:
            - type: string
            - type: 'null'
          title: Access Scope
        is_service_account:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Service Account
          default: false
        headers:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Headers
        mcp_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Id
        skill_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Skill Name
        target_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Target Id
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        mcp_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Name
        transport:
          anyOf:
            - type: string
            - type: 'null'
          title: Transport
        auth_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Auth Type
        api_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Api Key
        client_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Id
        client_secret:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Secret
        additional_scopes:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Additional Scopes
        share_user_token_across_other_agents:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Share User Token Across Other Agents
          default: true
        allowed_tools:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Allowed Tools
      type: object
      required:
        - kind
      title: ToolSuggestionChoice
      description: >-
        The tool the user picked. For a connector, either reference an existing

        connection (connection_id) OR carry a new-connection payload (security +
        meta)

        the backend persists — OAuth token, API key, AWS creds, etc.
    GatewayInviteRole:
      type: string
      enum:
        - member
        - admin
        - super_admin
        - viewer
      title: GatewayInviteRole
      description: >-
        Role for the invited teammate (maps to the invite-members edge fn
        payload).
    RequiredSecret:
      properties:
        name:
          type: string
          title: Name
          description: Env var name, e.g. AWS_ACCESS_KEY_ID.
        description:
          type: string
          title: Description
          description: What the secret is for (shown under the input).
          default: ''
        secret:
          type: boolean
          title: Secret
          description: Mask the input (true for secrets, false for plain config).
          default: true
        required:
          type: boolean
          title: Required
          description: Whether the value must be filled before submitting.
          default: true
      type: object
      required:
        - name
      title: RequiredSecret
      description: >-
        A single secret the card asks for (no value — the value is
        user-entered).
    GatewayQuestionOption:
      properties:
        id:
          type: string
          title: Id
          description: Stable id used to correlate the user's selection.
        label:
          type: string
          title: Label
          description: User-facing choice text.
        description:
          type: string
          title: Description
          description: Optional one-line elaboration.
          default: ''
      type: object
      required:
        - id
        - label
      title: GatewayQuestionOption
      description: One selectable choice on a question.
    GatewayToolKind:
      type: string
      enum:
        - action
        - custom_function
        - mcp
        - agent
        - workflow
        - skill
      title: GatewayToolKind
      description: >-
        Tool kind the suggestion / choice refers to (mirrors
        AddAgentToolRequest).
    GatewayConnectorConnection:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
          default: ''
        access_scope:
          anyOf:
            - type: string
            - type: 'null'
          title: Access Scope
        is_service_account:
          type: boolean
          title: Is Service Account
          default: false
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
      type: object
      required:
        - id
      title: GatewayConnectorConnection
      description: An existing connection the user can pick for a connector suggestion.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: API Key for authentication
      in: header
      name: x-api-key

````