feat(agent): add annotations field to AgentExecution

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 172
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gitpod%2Fgitpod-00ba82d543cfbd7d43712fb508d286a0a07b2aad1c6edf8084d794a903b09e3b.yml
-openapi_spec_hash: 381d9164ae462351125af601e9f5c951
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gitpod%2Fgitpod-e77dd932e4cfde041f712e0e130d6075754e2f5893bca0a03ee5cd0734b35089.yml
+openapi_spec_hash: faa844cfe771c3762e3a4d79b476cebf
 config_hash: ad1db65b32248aecda41b64586aac9ce

src/gitpod/resources/agents.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Optional
+from typing import Dict, Optional
 
 import httpx
 
@@ -537,6 +537,7 @@ def start_execution(
         self,
         *,
         agent_id: str | Omit = omit,
+        annotations: Dict[str, str] | Omit = omit,
         code_context: AgentCodeContextParam | Omit = omit,
         mode: AgentMode | Omit = omit,
         name: str | Omit = omit,
@@ -567,6 +568,10 @@ def start_execution(
           ```
 
         Args:
+          annotations: annotations are key-value pairs for tracking external context (e.g., Linear
+              session IDs, GitHub issue references). Keys should follow domain/name convention
+              (e.g., "linear.app/session-id").
+
           mode: mode specifies the operational mode for this agent execution If not specified,
               defaults to AGENT_MODE_EXECUTION
 
@@ -590,6 +595,7 @@ def start_execution(
             body=maybe_transform(
                 {
                     "agent_id": agent_id,
+                    "annotations": annotations,
                     "code_context": code_context,
                     "mode": mode,
                     "name": name,
@@ -1197,6 +1203,7 @@ async def start_execution(
         self,
         *,
         agent_id: str | Omit = omit,
+        annotations: Dict[str, str] | Omit = omit,
         code_context: AgentCodeContextParam | Omit = omit,
         mode: AgentMode | Omit = omit,
         name: str | Omit = omit,
@@ -1227,6 +1234,10 @@ async def start_execution(
           ```
 
         Args:
+          annotations: annotations are key-value pairs for tracking external context (e.g., Linear
+              session IDs, GitHub issue references). Keys should follow domain/name convention
+              (e.g., "linear.app/session-id").
+
           mode: mode specifies the operational mode for this agent execution If not specified,
               defaults to AGENT_MODE_EXECUTION
 
@@ -1250,6 +1261,7 @@ async def start_execution(
             body=await async_maybe_transform(
                 {
                     "agent_id": agent_id,
+                    "annotations": annotations,
                     "code_context": code_context,
                     "mode": mode,
                     "name": name,

src/gitpod/types/agent_execution.py

@@ -31,6 +31,9 @@ class Metadata(BaseModel):
      parts of Gitpod to function
     """
 
+    annotations: Optional[Dict[str, str]] = None
+    """annotations are key-value pairs for tracking external context."""
+
     created_at: Optional[datetime] = FieldInfo(alias="createdAt", default=None)
     """
     A Timestamp represents a point in time independent of any time zone or local

src/gitpod/types/agent_list_executions_params.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import List
+from typing import Dict, List
 from typing_extensions import Literal, Annotated, TypedDict
 
 from .._types import SequenceNotStr
@@ -24,6 +24,13 @@ class AgentListExecutionsParams(TypedDict, total=False):
 class Filter(TypedDict, total=False):
     agent_ids: Annotated[SequenceNotStr[str], PropertyInfo(alias="agentIds")]
 
+    annotations: Dict[str, str]
+    """annotations filters by key-value pairs.
+
+    Only executions containing all specified annotations (with matching values) are
+    returned.
+    """
+
     creator_ids: Annotated[SequenceNotStr[str], PropertyInfo(alias="creatorIds")]
 
     environment_ids: Annotated[SequenceNotStr[str], PropertyInfo(alias="environmentIds")]

src/gitpod/types/agent_start_execution_params.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Optional
+from typing import Dict, Optional
 from typing_extensions import Annotated, TypedDict
 
 from .._utils import PropertyInfo
@@ -15,6 +15,13 @@
 class AgentStartExecutionParams(TypedDict, total=False):
     agent_id: Annotated[str, PropertyInfo(alias="agentId")]
 
+    annotations: Dict[str, str]
+    """
+    annotations are key-value pairs for tracking external context (e.g., Linear
+    session IDs, GitHub issue references). Keys should follow domain/name convention
+    (e.g., "linear.app/session-id").
+    """
+
     code_context: Annotated[AgentCodeContextParam, PropertyInfo(alias="codeContext")]
 
     mode: AgentMode

tests/api_resources/test_agents.py

@@ -192,6 +192,7 @@ def test_method_list_executions_with_all_params(self, client: Gitpod) -> None:
             page_size=0,
             filter={
                 "agent_ids": ["b8a64cfa-43e2-4b9d-9fb3-07edc63f5971"],
+                "annotations": {"foo": "string"},
                 "creator_ids": ["string"],
                 "environment_ids": ["string"],
                 "project_ids": ["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
@@ -412,6 +413,7 @@ def test_method_start_execution(self, client: Gitpod) -> None:
     def test_method_start_execution_with_all_params(self, client: Gitpod) -> None:
         agent = client.agents.start_execution(
             agent_id="b8a64cfa-43e2-4b9d-9fb3-07edc63f5971",
+            annotations={"foo": "string"},
             code_context={
                 "context_url": {
                     "environment_class_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
@@ -718,6 +720,7 @@ async def test_method_list_executions_with_all_params(self, async_client: AsyncG
             page_size=0,
             filter={
                 "agent_ids": ["b8a64cfa-43e2-4b9d-9fb3-07edc63f5971"],
+                "annotations": {"foo": "string"},
                 "creator_ids": ["string"],
                 "environment_ids": ["string"],
                 "project_ids": ["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
@@ -938,6 +941,7 @@ async def test_method_start_execution(self, async_client: AsyncGitpod) -> None:
     async def test_method_start_execution_with_all_params(self, async_client: AsyncGitpod) -> None:
         agent = await async_client.agents.start_execution(
             agent_id="b8a64cfa-43e2-4b9d-9fb3-07edc63f5971",
+            annotations={"foo": "string"},
             code_context={
                 "context_url": {
                     "environment_class_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",