Add Hosted Agents /v2/agents/configs OpenAPI (MARSOHS-741)

specification/DigitalOcean-public.v2.yaml

@@ -60,6 +60,19 @@ tags:
       The Add-Ons API allows you to manage these resources, including creating, listing, and retrieving
       details about specific add-on resources.
 
+  - name: Agents
+    description: |-
+      Hosted Agents API under `/v2/agents`. Sessions (`/v2/agents/sessions`)
+      represent a managed agent + sandbox pair. Product provenance is exposed
+      via `session.origin` (`direct` | `simulation` | `evaluation`). ListSessions
+      omits simulation and evaluation sessions server-side so customer surfaces
+      stay free of product-owned internal runs; GetSession by session_id still
+      returns those sessions for the owning product workflow.
+
+      Agent Configs (`/v2/agents/configs`) are immutable team-scoped manifests
+      that sessions can be created from. Soft-delete releases the active name
+      while keeping `config_id` resolvable for existing sessions.
+
   - name: Apps
     description: |-
       App Platform is a Platform-as-a-Service (PaaS) offering from DigitalOcean that allows
@@ -781,6 +794,75 @@ paths:
     patch:
       $ref: "resources/addons/addons_update_plan.yml"
 
+  /v2/agents/configs:
+    get:
+      $ref: "resources/agents/agents_list_configs.yml"
+    post:
+      $ref: "resources/agents/agents_create_config.yml"
+  /v2/agents/configs/{config_id}:
+    get:
+      $ref: "resources/agents/agents_get_config.yml"
+    delete:
+      $ref: "resources/agents/agents_delete_config.yml"
+  /v2/agents/configs/{config_id}/sessions:
+    get:
+      $ref: "resources/agents/agents_list_config_sessions.yml"
+  /v2/agents/sessions:
+    get:
+      $ref: "resources/agents/agents_list_sessions.yml"
+    post:
+      $ref: "resources/agents/agents_create_session.yml"
+  /v2/agents/sessions/policy/validate:
+    post:
+      $ref: "resources/agents/agents_validate_session_policy.yml"
+  /v2/agents/sessions/sandbox/sizes:
+    get:
+      $ref: "resources/agents/agents_list_session_sandbox_sizes.yml"
+  /v2/agents/sessions/{session_id}:
+    delete:
+      $ref: "resources/agents/agents_delete_session.yml"
+    get:
+      $ref: "resources/agents/agents_get_session.yml"
+  /v2/agents/sessions/{session_id}/hitl/{request_id}:
+    post:
+      $ref: "resources/agents/agents_post_session_hitl.yml"
+  /v2/agents/sessions/{session_id}/input:
+    post:
+      $ref: "resources/agents/agents_create_session_input.yml"
+  /v2/agents/sessions/{session_id}/pause:
+    post:
+      $ref: "resources/agents/agents_post_session_pause.yml"
+  /v2/agents/sessions/{session_id}/resume:
+    post:
+      $ref: "resources/agents/agents_post_session_resume.yml"
+  /v2/agents/sessions/{session_id}/sandbox/exec:
+    post:
+      $ref: "resources/agents/agents_post_session_sandbox_exec.yml"
+  /v2/agents/sessions/{session_id}/stream:
+    get:
+      $ref: "resources/agents/agents_get_session_stream.yml"
+  /v2/agents/sessions/{session_id}/workspace/download:
+    get:
+      $ref: "resources/agents/agents_get_session_workspace_download.yml"
+  /v2/agents/sessions/{session_id}/workspace/transfers:
+    post:
+      $ref: "resources/agents/agents_create_session_workspace_transfer.yml"
+  /v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id}:
+    get:
+      $ref: "resources/agents/agents_get_session_workspace_transfer.yml"
+  /v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id}/cancel:
+    post:
+      $ref: "resources/agents/agents_cancel_session_workspace_transfer.yml"
+  /v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id}/commit:
+    post:
+      $ref: "resources/agents/agents_commit_session_workspace_transfer.yml"
+  /v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id}/part-upload-urls:
+    post:
+      $ref: "resources/agents/agents_create_session_workspace_part_upload_urls.yml"
+  /v2/agents/sessions/{session_id}/workspace/upload:
+    post:
+      $ref: "resources/agents/agents_create_session_workspace_upload.yml"
+
   /v2/apps:
     get:
       $ref: "resources/apps/apps_list.yml"

specification/resources/agents/agents_cancel_session_workspace_transfer.yml

@@ -0,0 +1,70 @@
+operationId: agents_cancel_session_workspace_transfer
+summary: Cancel a staged workspace transfer.
+description: 'Aborts an in-flight transfer. Idempotent: cancelling an already-terminal transfer returns
+  `aborted: false` with the current status. The request body is optional.'
+tags:
+- Agents
+parameters:
+- in: path
+  name: session_id
+  required: true
+  description: The session UUID.
+  schema:
+    type: string
+    example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+  example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+- in: path
+  name: transfer_id
+  required: true
+  description: The workspace transfer identifier.
+  schema:
+    type: string
+    example: tr_example
+  example: tr_example
+requestBody:
+  required: false
+  content:
+    application/json:
+      schema:
+        type: object
+        properties:
+          reason:
+            type: string
+            description: Optional caller-visible audit/debug context.
+            example: example
+responses:
+  '200':
+    description: Cancel processed.
+    headers: &id001
+      ratelimit-limit:
+        $ref: ../../shared/headers.yml#/ratelimit-limit
+      ratelimit-remaining:
+        $ref: ../../shared/headers.yml#/ratelimit-remaining
+      ratelimit-reset:
+        $ref: ../../shared/headers.yml#/ratelimit-reset
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/workspace_transfer_cancelled
+  '401':
+    $ref: ../../shared/responses/unauthorized.yml
+  '404':
+    $ref: ../../shared/responses/not_found.yml
+  '501':
+    description: Cancel is not supported by the active sandbox driver.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '429':
+    $ref: ../../shared/responses/too_many_requests.yml
+  '500':
+    $ref: ../../shared/responses/server_error.yml
+  default:
+    $ref: ../../shared/responses/unexpected_error.yml
+x-codeSamples:
+- $ref: examples/curl/agents_cancel_session_workspace_transfer.yml
+security:
+- bearer_auth:
+  - agents:create

specification/resources/agents/agents_commit_session_workspace_transfer.yml

@@ -0,0 +1,86 @@
+operationId: agents_commit_session_workspace_transfer
+summary: Finalize a staged upload.
+description: Upload only. Call once, after all parts have been uploaded. Completes the multipart upload
+  and starts the asynchronous import into the workspace. Responds 202; poll the transfer until `completed`
+  or `failed`.
+tags:
+- Agents
+parameters:
+- in: path
+  name: session_id
+  required: true
+  description: The session UUID.
+  schema:
+    type: string
+    example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+  example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+- in: path
+  name: transfer_id
+  required: true
+  description: The workspace transfer identifier.
+  schema:
+    type: string
+    example: tr_example
+  example: tr_example
+requestBody:
+  required: false
+  content:
+    application/json:
+      schema:
+        type: object
+        properties:
+          sha256:
+            type: string
+            description: Optional lowercase hex SHA-256. Must match the value supplied at create when
+              both are set.
+            example: example
+responses:
+  '202':
+    description: Upload committed; import in progress.
+    headers: &id001
+      ratelimit-limit:
+        $ref: ../../shared/headers.yml#/ratelimit-limit
+      ratelimit-remaining:
+        $ref: ../../shared/headers.yml#/ratelimit-remaining
+      ratelimit-reset:
+        $ref: ../../shared/headers.yml#/ratelimit-reset
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/workspace_upload_committed
+  '400':
+    description: Missing transfer_id, sha256 mismatch, or invalid JSON.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '401':
+    $ref: ../../shared/responses/unauthorized.yml
+  '404':
+    $ref: ../../shared/responses/not_found.yml
+  '409':
+    description: Transfer is not in a committable state.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '501':
+    description: Staged upload is not supported by the active sandbox driver.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '429':
+    $ref: ../../shared/responses/too_many_requests.yml
+  '500':
+    $ref: ../../shared/responses/server_error.yml
+  default:
+    $ref: ../../shared/responses/unexpected_error.yml
+x-codeSamples:
+- $ref: examples/curl/agents_commit_session_workspace_transfer.yml
+security:
+- bearer_auth:
+  - agents:create

specification/resources/agents/agents_create_config.yml

@@ -0,0 +1,69 @@
+operationId: agents_create_config
+summary: Create an Agent Config (manifest + secrets in one request).
+description: Accepts name, agents.yaml text, and optional write-only secret values in one request. Responses
+  never echo secret values; GET/create may include credential slot metadata (name/source/provider only). Configs
+  are immutable after create.
+tags:
+- Agents
+requestBody:
+  required: true
+  content:
+    application/json:
+      schema:
+        $ref: models/definitions.yml#/agent_config_create_request
+  description: Unified Agent Config create body. secrets/oauth_assignments are write-only and never returned.
+responses:
+  '201':
+    description: Config created.
+    headers: &id001
+      ratelimit-limit:
+        $ref: ../../shared/headers.yml#/ratelimit-limit
+      ratelimit-remaining:
+        $ref: ../../shared/headers.yml#/ratelimit-remaining
+      ratelimit-reset:
+        $ref: ../../shared/headers.yml#/ratelimit-reset
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/agent_config_response
+  '400':
+    description: Invalid name, JSON wrapper, or agents.yaml manifest.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '401':
+    $ref: ../../shared/responses/unauthorized.yml
+  '409':
+    description: An active config with this name already exists for the team.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '413':
+    description: Request body exceeds 1 MiB.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '415':
+    description: Content-Type is not application/json.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '500':
+    $ref: ../../shared/responses/server_error.yml
+  '429':
+    $ref: ../../shared/responses/too_many_requests.yml
+  default:
+    $ref: ../../shared/responses/unexpected_error.yml
+x-codeSamples:
+- $ref: examples/curl/agents_create_config.yml
+security:
+- bearer_auth:
+  - agents:create