From e60fbcd358a9443ad6b839705984ec547fce6b72 Mon Sep 17 00:00:00 2001 From: Saurav Kumar Date: Mon, 12 Oct 2026 15:59:18 +0530 Subject: [PATCH 1/2] Rename 'agent' to 'environment' in Signals spec descriptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update all descriptive text in Signals OpenAPI spec files to use 'environment' instead of 'agent' when referring to Harness Runtime environments, aligning with product-docs terminology. Field names (agent_id), enum values (source: agent, type: agent), and example values are unchanged — only human-readable descriptions, summaries, and the Signals tag description are updated. 18 files, 42 lines changed. --- specification/DigitalOcean-public.v2.yaml | 6 +++--- specification/resources/signals/models/agent_consent.yml | 8 ++++---- specification/resources/signals/models/consent_record.yml | 8 ++++---- .../resources/signals/models/create_deletion_request.yml | 6 +++--- .../resources/signals/models/create_export_request.yml | 2 +- specification/resources/signals/models/deletion_job.yml | 4 ++-- specification/resources/signals/models/export_job.yml | 2 +- specification/resources/signals/models/list_consents.yml | 2 +- specification/resources/signals/models/session.yml | 2 +- specification/resources/signals/parameters.yml | 6 +++--- .../signals/responses/agent_consent_response.yml | 2 +- .../resources/signals/signals_create_deletion.yml | 8 ++++---- specification/resources/signals/signals_get_consent.yml | 8 ++++---- specification/resources/signals/signals_list_consents.yml | 2 +- .../resources/signals/signals_list_dialogues.yml | 2 +- specification/resources/signals/signals_list_sessions.yml | 4 ++-- .../resources/signals/signals_update_consent.yml | 8 ++++---- .../resources/signals/signals_update_team_consent.yml | 4 ++-- 18 files changed, 42 insertions(+), 42 deletions(-) diff --git a/specification/DigitalOcean-public.v2.yaml b/specification/DigitalOcean-public.v2.yaml index dace9f4fc..4ba5ba953 100644 --- a/specification/DigitalOcean-public.v2.yaml +++ b/specification/DigitalOcean-public.v2.yaml @@ -594,18 +594,18 @@ tags: - name: Signals description: |- - The DigitalOcean Signals API provides observability for agent + The DigitalOcean Signals API provides observability for environment conversations, such as Harness Runtime conversations and Serverless Inference chat completions, detecting behavioral signals such as user disengagement, execution failures, and satisfaction indicators. Use the consent endpoints to manage whether signals collection is - enabled — per agent for Harness Runtime (`source=agent`) and per team + enabled — per environment for Harness Runtime (`source=agent`) and per team for Serverless Inference chat completions (`source=inference`) — the session endpoints to browse conversations and their detected signals, the export endpoints to create downloadable archives of signals data for offline analysis, and the deletion endpoints to permanently delete - Signals conversations for an agent or Serverless Inference + Signals conversations for an environment or Serverless Inference conversations for a whole team (aggregated Insights or metrics summaries may still remain). diff --git a/specification/resources/signals/models/agent_consent.yml b/specification/resources/signals/models/agent_consent.yml index 73783714f..7d4662edf 100644 --- a/specification/resources/signals/models/agent_consent.yml +++ b/specification/resources/signals/models/agent_consent.yml @@ -1,5 +1,5 @@ type: object -description: Consent details for a specific agent. +description: Consent details for a specific environment. properties: id: type: integer @@ -14,17 +14,17 @@ properties: enum: - agent description: >- - The source this consent applies to. Always `agent` for per-agent + The source this consent applies to. Always `agent` for per-environment records returned by this endpoint. example: agent agent_id: type: string format: uuid - description: The unique identifier of the agent. For Harness Runtime, this is the Environment Config ID. + description: The unique identifier of the environment. For Harness Runtime, this is the Environment Config ID. example: 019fb3d2-8a56-72cc-8bf9-9d21510b2a99 enabled: type: boolean - description: Whether signals collection is enabled for this agent. + description: Whether signals collection is enabled for this environment. example: true updated_at: type: string diff --git a/specification/resources/signals/models/consent_record.yml b/specification/resources/signals/models/consent_record.yml index 14c8fc13d..132f0f081 100644 --- a/specification/resources/signals/models/consent_record.yml +++ b/specification/resources/signals/models/consent_record.yml @@ -1,7 +1,7 @@ type: object description: >- A consent record indicating whether signals collection is enabled for a - source. Records with `source: agent` apply to one agent; the record with + source. Records with `source: agent` apply to one environment; the record with `source: inference` applies to the whole team. properties: id: @@ -18,16 +18,16 @@ properties: - agent - inference description: >- - The source this consent applies to. `agent` is per-agent consent for + The source this consent applies to. `agent` is per-environment consent for Harness Runtime; `inference` is team-level consent for Serverless Inference chat completions. example: agent agent_id: type: string description: >- - The unique identifier of the agent. For Harness Runtime, this is the + The unique identifier of the environment. For Harness Runtime, this is the Environment Config ID. Empty for team-level records (`source: - inference`), which are not tied to an agent. + inference`), which are not tied to an environment. example: 019fb3d2-8a56-72cc-8bf9-9d21510b2a99 enabled: type: boolean diff --git a/specification/resources/signals/models/create_deletion_request.yml b/specification/resources/signals/models/create_deletion_request.yml index d1402af37..d8fb54c0f 100644 --- a/specification/resources/signals/models/create_deletion_request.yml +++ b/specification/resources/signals/models/create_deletion_request.yml @@ -5,7 +5,7 @@ properties: type: string description: >- The scope of the deletion. `agent` deletes Signals conversations for one - Harness Runtime agent and requires `agent_id`. `inference` deletes + Harness Runtime environment and requires `agent_id`. `inference` deletes Serverless Inference Signals conversations for the whole team (team-wide; omit `agent_id`). enum: @@ -21,8 +21,8 @@ properties: type: string format: uuid description: >- - The Harness Runtime Environment Config ID of the agent whose - conversations should be deleted. This is the agent UUID (`agent_id`). + The Harness Runtime Environment Config ID of the environment whose + conversations should be deleted. Required when `type` is `agent`; must be omitted when `type` is `inference`. example: 01a10d3f-2c09-764f-99f8-458e521627f3 diff --git a/specification/resources/signals/models/create_export_request.yml b/specification/resources/signals/models/create_export_request.yml index 1feffdab7..575d24a19 100644 --- a/specification/resources/signals/models/create_export_request.yml +++ b/specification/resources/signals/models/create_export_request.yml @@ -4,7 +4,7 @@ properties: agent_id: type: string format: uuid - description: The agent whose data should be exported. For Harness Runtime, this is the Environment Config ID. + description: The environment whose data should be exported. For Harness Runtime, this is the Environment Config ID. example: 01a0f3d5-b58d-7c99-a743-7ca0397b7f5d signal_type: type: array diff --git a/specification/resources/signals/models/deletion_job.yml b/specification/resources/signals/models/deletion_job.yml index cbdb90797..82fc3ca8b 100644 --- a/specification/resources/signals/models/deletion_job.yml +++ b/specification/resources/signals/models/deletion_job.yml @@ -1,7 +1,7 @@ type: object description: >- A deletion job that permanently removes Signals conversations for one - Harness Runtime agent, or Serverless Inference Signals conversations for a + Harness Runtime environment, or Serverless Inference Signals conversations for a whole team. Aggregated Insights or metrics summaries may still remain. properties: team_id: @@ -17,7 +17,7 @@ properties: type: string description: >- The scope of the deletion. `agent` deletes Signals conversations for one - Harness Runtime agent. `inference` deletes Serverless Inference Signals + Harness Runtime environment. `inference` deletes Serverless Inference Signals conversations for the whole team. enum: - agent diff --git a/specification/resources/signals/models/export_job.yml b/specification/resources/signals/models/export_job.yml index 48b978c23..7c9a28a68 100644 --- a/specification/resources/signals/models/export_job.yml +++ b/specification/resources/signals/models/export_job.yml @@ -9,7 +9,7 @@ properties: agent_id: type: string format: uuid - description: The agent whose data is being exported. For Harness Runtime, this is the Environment Config ID. + description: The environment whose data is being exported. For Harness Runtime, this is the Environment Config ID. example: 01a0f3d5-b58d-7c99-a743-7ca0397b7f5d status: type: string diff --git a/specification/resources/signals/models/list_consents.yml b/specification/resources/signals/models/list_consents.yml index 9032c5e2d..844b41f6e 100644 --- a/specification/resources/signals/models/list_consents.yml +++ b/specification/resources/signals/models/list_consents.yml @@ -4,7 +4,7 @@ properties: consents: type: array description: >- - A list of consent records for the team. Includes per-agent records + A list of consent records for the team. Includes per-environment records (`source: agent`) and, when set, the team-level inference record (`source: inference`). items: diff --git a/specification/resources/signals/models/session.yml b/specification/resources/signals/models/session.yml index af4a7b75e..b79be02c0 100644 --- a/specification/resources/signals/models/session.yml +++ b/specification/resources/signals/models/session.yml @@ -1,5 +1,5 @@ type: object -description: A session represents a conversation monitored by Signals, such as a Harness Runtime agent session or a Serverless Inference chat completion. +description: A session represents a conversation monitored by Signals, such as a Harness Runtime environment session or a Serverless Inference chat completion. properties: session_id: type: string diff --git a/specification/resources/signals/parameters.yml b/specification/resources/signals/parameters.yml index 78e80def2..0e9e8eceb 100644 --- a/specification/resources/signals/parameters.yml +++ b/specification/resources/signals/parameters.yml @@ -1,7 +1,7 @@ agent_id: in: path name: agent_id - description: A unique identifier for an agent. For Harness Runtime, this is the Environment Config ID. + description: A unique identifier for an environment. For Harness Runtime, this is the Environment Config ID. required: true schema: type: string @@ -32,7 +32,7 @@ source: in: query name: source description: >- - Filter consent records by source. `agent` returns per-agent records + Filter consent records by source. `agent` returns per-environment records (Harness Runtime); `inference` returns the team-level record for Serverless Inference chat completions. When omitted, records for all sources are returned. @@ -50,7 +50,7 @@ source_required: description: >- The consent source to update. Only team-level sources are accepted on this endpoint; currently `inference` (Serverless Inference chat - completions). Per-agent consent (`agent`) is managed with + completions). Per-environment consent (`agent`) is managed with `PUT /v1/consent/{agent_id}` instead. required: true schema: diff --git a/specification/resources/signals/responses/agent_consent_response.yml b/specification/resources/signals/responses/agent_consent_response.yml index 242aaaa3a..bd495028a 100644 --- a/specification/resources/signals/responses/agent_consent_response.yml +++ b/specification/resources/signals/responses/agent_consent_response.yml @@ -1,4 +1,4 @@ -description: A single agent consent record. +description: A single environment consent record. headers: ratelimit-limit: diff --git a/specification/resources/signals/signals_create_deletion.yml b/specification/resources/signals/signals_create_deletion.yml index 93f652982..05f2732ea 100644 --- a/specification/resources/signals/signals_create_deletion.yml +++ b/specification/resources/signals/signals_create_deletion.yml @@ -8,11 +8,11 @@ description: | Two deletion types are supported: - - `agent` — deletes Signals conversations for one Harness Runtime agent and - turns off collection for that agent. Requires `agent_id`, which is the - agent's Environment Config ID (the agent UUID). On create, matching + - `agent` — deletes Signals conversations for one Harness Runtime environment and + turns off collection for that environment. Requires `agent_id`, which is the + environment's Environment Config ID. On create, matching conversations are hidden from Signals reads immediately. Wait until the - job is `complete` before enabling Signals for the agent again. + job is `complete` before enabling Signals for the environment again. - `inference` — deletes Serverless Inference Signals conversations for your whole team (team-wide; not limited to one endpoint or model) that were collected at or before the deletion request, and turns off team inference diff --git a/specification/resources/signals/signals_get_consent.yml b/specification/resources/signals/signals_get_consent.yml index 4d94d15e6..e3f8fdb04 100644 --- a/specification/resources/signals/signals_get_consent.yml +++ b/specification/resources/signals/signals_get_consent.yml @@ -1,13 +1,13 @@ operationId: signals_get_consent -summary: Retrieve Consent for an Agent +summary: Retrieve Consent for an Environment description: | - To retrieve the consent record for a specific agent, send a GET + To retrieve the consent record for a specific environment, send a GET request to `/v1/consent/{agent_id}`. The response includes an `enabled` - field indicating whether signals collection is on for this agent. + field indicating whether signals collection is on for this environment. - This endpoint only serves per-agent (`source: agent`) records. Team-level + This endpoint only serves per-environment (`source: agent`) records. Team-level inference consent is read from `GET /v1/consent?source=inference`. tags: diff --git a/specification/resources/signals/signals_list_consents.yml b/specification/resources/signals/signals_list_consents.yml index 6053e11a3..2dc5121ce 100644 --- a/specification/resources/signals/signals_list_consents.yml +++ b/specification/resources/signals/signals_list_consents.yml @@ -5,7 +5,7 @@ summary: List All Consent Records description: | To list all signals consent records for your team, send a GET request to `/v1/consent`. Each record indicates whether signals collection is enabled - for a source: per-agent records (`source: agent`) for Harness Runtime, and + for a source: per-environment records (`source: agent`) for Harness Runtime, and the team-level record (`source: inference`) for Serverless Inference chat completions. diff --git a/specification/resources/signals/signals_list_dialogues.yml b/specification/resources/signals/signals_list_dialogues.yml index aed5013c5..3497de98f 100644 --- a/specification/resources/signals/signals_list_dialogues.yml +++ b/specification/resources/signals/signals_list_dialogues.yml @@ -5,7 +5,7 @@ summary: List Dialogues for a Session description: | To list the dialogue turns within a specific session, send a GET request to `/v1/signals/sessions/{session_id}/dialogues`. Each dialogue represents a - single turn of conversation between a user and the agent, along with + single turn of conversation between a user and the environment, along with any signals detected. Results are paginated using cursor-based pagination. tags: diff --git a/specification/resources/signals/signals_list_sessions.yml b/specification/resources/signals/signals_list_sessions.yml index c0bd6974f..ef780dae6 100644 --- a/specification/resources/signals/signals_list_sessions.yml +++ b/specification/resources/signals/signals_list_sessions.yml @@ -1,9 +1,9 @@ operationId: signals_list_agent_sessions -summary: List Sessions for an Agent +summary: List Sessions for an Environment description: | - To list signals sessions for a specific agent, send a GET request to + To list signals sessions for a specific environment, send a GET request to `/v1/signals/agents/{agent_id}/sessions`. Results are paginated using cursor-based pagination with `limit` and `after` parameters. diff --git a/specification/resources/signals/signals_update_consent.yml b/specification/resources/signals/signals_update_consent.yml index 8d91d01bc..5a91c7d67 100644 --- a/specification/resources/signals/signals_update_consent.yml +++ b/specification/resources/signals/signals_update_consent.yml @@ -1,13 +1,13 @@ operationId: signals_update_consent -summary: Update Consent for an Agent +summary: Update Consent for an Environment description: | - To enable or disable signals collection for a specific agent, send a + To enable or disable signals collection for a specific environment, send a PUT request to `/v1/consent/{agent_id}` with an `enabled` boolean in the request body. - This endpoint only manages per-agent (`source: agent`) consent. To manage + This endpoint only manages per-environment (`source: agent`) consent. To manage team-level consent for Serverless Inference, use `PUT /v1/consent?source=inference` instead. @@ -26,7 +26,7 @@ requestBody: properties: enabled: type: boolean - description: Whether to enable signals collection for this agent. + description: Whether to enable signals collection for this environment. required: - enabled example: diff --git a/specification/resources/signals/signals_update_team_consent.yml b/specification/resources/signals/signals_update_team_consent.yml index b7069c3b3..6306da756 100644 --- a/specification/resources/signals/signals_update_team_consent.yml +++ b/specification/resources/signals/signals_update_team_consent.yml @@ -10,8 +10,8 @@ description: | made by your team. To revoke consent, send the same request with `enabled` set to `false`. - The `source` query parameter is required. Per-agent consent for Harness - Runtime agents is managed with `PUT /v1/consent/{agent_id}` instead. + The `source` query parameter is required. Per-environment consent for Harness + Runtime environments is managed with `PUT /v1/consent/{agent_id}` instead. tags: - Signals From 121667ce269d36676d0454bbe65c4ba6b2603d23 Mon Sep 17 00:00:00 2001 From: Saurav Kumar Date: Mon, 12 Oct 2026 16:15:39 +0530 Subject: [PATCH 2/2] Clarify agent_id reference in deletion request and endpoint descriptions --- .../resources/signals/models/create_deletion_request.yml | 2 +- specification/resources/signals/signals_create_deletion.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/resources/signals/models/create_deletion_request.yml b/specification/resources/signals/models/create_deletion_request.yml index d8fb54c0f..23a12420e 100644 --- a/specification/resources/signals/models/create_deletion_request.yml +++ b/specification/resources/signals/models/create_deletion_request.yml @@ -22,7 +22,7 @@ properties: format: uuid description: >- The Harness Runtime Environment Config ID of the environment whose - conversations should be deleted. + conversations should be deleted. This is the environment's `agent_id`. Required when `type` is `agent`; must be omitted when `type` is `inference`. example: 01a10d3f-2c09-764f-99f8-458e521627f3 diff --git a/specification/resources/signals/signals_create_deletion.yml b/specification/resources/signals/signals_create_deletion.yml index 05f2732ea..44673998f 100644 --- a/specification/resources/signals/signals_create_deletion.yml +++ b/specification/resources/signals/signals_create_deletion.yml @@ -10,7 +10,7 @@ description: | - `agent` — deletes Signals conversations for one Harness Runtime environment and turns off collection for that environment. Requires `agent_id`, which is the - environment's Environment Config ID. On create, matching + environment's Environment Config ID (the environment's `agent_id`). On create, matching conversations are hidden from Signals reads immediately. Wait until the job is `complete` before enabling Signals for the environment again. - `inference` — deletes Serverless Inference Signals conversations for your