From fb0324b2f90317bdd6deb9cc7dec6470ff3a5dc2 Mon Sep 17 00:00:00 2001
From: Vijay Kalmath <vijay.kalmath@scale.com>
Date: Tue, 28 Jul 2026 14:44:54 -0400
Subject: [PATCH] feat(task-messages): add optional agent_path to TaskMessage
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Streamed task-message events carry only a task_id, so events emitted by
multiple agents into a single task stream cannot be attributed to their
source. Add an optional agent_path to the TaskMessage schema — a single
agent id, or a root-to-emitter path for nested agents sharing one stream.
Stream events already carry it via parent_task_message, so TaskMessage is
the right OpenAPI surface for per-agent attribution.

Additive and backward-compatible (optional, defaults to null); stream-only,
so no entity/storage change. Regenerated openapi.yaml via make gen-openapi.

The generated Python SDK (scale-agentex-python) picks this up via the
automated Stainless flow; the runtime that stamps agent_path lands in
scale-agentex-python#474.
---
 agentex/openapi.yaml                     | 12 ++++++++++++
 agentex/src/api/schemas/task_messages.py |  9 +++++++++
 2 files changed, 21 insertions(+)

diff --git a/agentex/openapi.yaml b/agentex/openapi.yaml
index b8ab2b22..bcea9420 100644
--- a/agentex/openapi.yaml
+++ b/agentex/openapi.yaml
@@ -6605,6 +6605,18 @@ components:
           type: string
           title: Task Id
           description: ID of the task this message belongs to
+        agent_path:
+          anyOf:
+          - type: string
+          - items:
+              type: string
+            type: array
+          - type: 'null'
+          title: Agent Path
+          description: 'Identifier of the agent that emitted this message: a single
+            agent id, or a root-to-emitter path (e.g. ["researcher", "subagent-abc"])
+            when nested agents share one task stream. Lets consumers attribute and
+            group streamed events by agent.'
         content:
           $ref: '#/components/schemas/TaskMessageContent'
           description: The content of the message. This content is not OpenAI compatible.
diff --git a/agentex/src/api/schemas/task_messages.py b/agentex/src/api/schemas/task_messages.py
index 50223c03..c564bb50 100644
--- a/agentex/src/api/schemas/task_messages.py
+++ b/agentex/src/api/schemas/task_messages.py
@@ -217,6 +217,15 @@ class TaskMessage(BaseModel):
 
     id: str | None = Field(None, description="The task message's unique id")
     task_id: str = Field(..., description="ID of the task this message belongs to")
+    agent_path: str | list[str] | None = Field(
+        None,
+        description=(
+            "Identifier of the agent that emitted this message: a single agent id, "
+            'or a root-to-emitter path (e.g. ["researcher", "subagent-abc"]) when '
+            "nested agents share one task stream. Lets consumers attribute and group "
+            "streamed events by agent."
+        ),
+    )
     content: TaskMessageContent = Field(
         ...,
         description="The content of the message. This content is not OpenAI compatible. These are messages that are meant to be displayed to the user.",