ellipsis-dev 0.46.0__tar.gz → 0.47.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: ellipsis-dev
3
- Version: 0.46.0
3
+ Version: 0.47.0
4
4
  Summary: Python SDK for the Ellipsis agents platform: every /v1 operation, sync and async.
5
5
  Project-URL: Homepage, https://www.ellipsis.dev
6
6
  Project-URL: Documentation, https://www.ellipsis.dev/docs/api
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "ellipsis-dev"
7
- version = "0.46.0"
7
+ version = "0.47.0"
8
8
  description = "Python SDK for the Ellipsis agents platform: every /v1 operation, sync and async."
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -18,7 +18,6 @@ from . import models
18
18
  from ._pagination import AsyncPage, SyncPage
19
19
  from ._session_handle import AsyncSessionsSugar, SyncSessionsSugar
20
20
  from ._transport import (
21
- DEFAULT_BASE_URL,
22
21
  DEFAULT_TIMEOUT_SECONDS,
23
22
  MAX_RETRIES,
24
23
  AsyncTransport,
@@ -748,10 +747,13 @@ class _SyncAgents:
748
747
 
749
748
  def list(
750
749
  self,
750
+ *,
751
+ label: Union[List[str], None] = None,
752
+ annotation: Union[List[str], None] = None,
751
753
  ) -> models.AgentsListResponse:
752
754
  """List Agents
753
755
 
754
- List agents.
756
+ List agents, optionally only those with the given labels and annotations.
755
757
 
756
758
  Required permissions: read:configs.
757
759
  API key: Supported.
@@ -761,8 +763,14 @@ class _SyncAgents:
761
763
  Grant match patterns can further restrict access to individual resources.
762
764
  """
763
765
  path = "/v1/agents"
766
+ query = build_query(
767
+ {
768
+ "label": label,
769
+ "annotation": annotation,
770
+ }
771
+ )
764
772
  response = self._transport.request(
765
- "GET", path, response_model=models.AgentsListResponse
773
+ "GET", path, response_model=models.AgentsListResponse, query=query
766
774
  )
767
775
  assert response is not None
768
776
  return response
@@ -819,7 +827,7 @@ class _SyncAgents:
819
827
  idempotency_key: Union[str, None] = None,
820
828
  images: Union[List[models.ImageAttachment], None] = None,
821
829
  input: Union[dict[str, Any], None] = None,
822
- metadata: Union[dict[str, Union[str, None]], None] = None,
830
+ metadata: Union[models.ConfigMetadataPatch, None] = None,
823
831
  output: Union[models.OutputConfig, None] = None,
824
832
  permissions: Union[models.PermissionsConfig_Input, None] = None,
825
833
  skills: Union[List[models.SkillRef_Input], None] = None,
@@ -1196,10 +1204,13 @@ class _SyncEnvironments:
1196
1204
 
1197
1205
  def list(
1198
1206
  self,
1207
+ *,
1208
+ label: Union[List[str], None] = None,
1209
+ annotation: Union[List[str], None] = None,
1199
1210
  ) -> models.EnvironmentsListResponse:
1200
1211
  """List Environments
1201
1212
 
1202
- List saved environments.
1213
+ List saved environments, optionally only those with the given labels and annotations.
1203
1214
 
1204
1215
  Required permissions: read:environments.
1205
1216
  API key: Supported.
@@ -1208,8 +1219,14 @@ class _SyncEnvironments:
1208
1219
  Higher permission levels include lower levels: read < write < delete.
1209
1220
  """
1210
1221
  path = "/v1/environments"
1222
+ query = build_query(
1223
+ {
1224
+ "label": label,
1225
+ "annotation": annotation,
1226
+ }
1227
+ )
1211
1228
  response = self._transport.request(
1212
- "GET", path, response_model=models.EnvironmentsListResponse
1229
+ "GET", path, response_model=models.EnvironmentsListResponse, query=query
1213
1230
  )
1214
1231
  assert response is not None
1215
1232
  return response
@@ -1914,13 +1931,15 @@ class _SyncSessions(SyncSessionsSugar):
1914
1931
  author_id: Union[int, None] = None,
1915
1932
  repo: Union[str, None] = None,
1916
1933
  status: Union[List[models.SessionStatus], None] = None,
1934
+ label: Union[List[str], None] = None,
1935
+ annotation: Union[List[str], None] = None,
1917
1936
  ) -> SyncPage[models.Session, models.SessionsListResponse]:
1918
1937
  """List Sessions
1919
1938
 
1920
1939
  List cloud agent sessions, newest first.
1921
1940
 
1922
1941
  Optionally filtered by agent (id or name), source, service, handler, time
1923
- window, attributed author, repository, and status.
1942
+ window, attributed author, repository, status, labels, and annotations.
1924
1943
 
1925
1944
  Required permissions: read:sessions.
1926
1945
  API key: Supported.
@@ -1944,6 +1963,8 @@ class _SyncSessions(SyncSessionsSugar):
1944
1963
  "author_id": author_id,
1945
1964
  "repo": repo,
1946
1965
  "status": status,
1966
+ "label": label,
1967
+ "annotation": annotation,
1947
1968
  }
1948
1969
  )
1949
1970
  response = self._transport.request(
@@ -1966,6 +1987,8 @@ class _SyncSessions(SyncSessionsSugar):
1966
1987
  author_id=author_id,
1967
1988
  repo=repo,
1968
1989
  status=status,
1990
+ label=label,
1991
+ annotation=annotation,
1969
1992
  ),
1970
1993
  )
1971
1994
 
@@ -2052,14 +2075,15 @@ class _SyncSessions(SyncSessionsSugar):
2052
2075
  Send a message to a session.
2053
2076
 
2054
2077
  409 for mention, non-interactive, closed, archived, and
2055
- out-of-budget sessions. Returns the created message; a retried send with the
2078
+ out-of-budget sessions. 403 when a session token sends to its own
2079
+ session. Returns the created message; a retried send with the
2056
2080
  same idempotency_key returns the original one. The message is
2057
2081
  answered once the session's status is `idle` or `closed`.
2058
2082
 
2059
2083
  Required permissions: write:sessions.
2060
2084
  API key: Supported.
2061
2085
  CLI user token: Supported.
2062
- Session token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
2086
+ Session token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration. Never the token's own session.
2063
2087
  Higher permission levels include lower levels: read < write < delete.
2064
2088
  Grant match patterns can further restrict access to individual resources.
2065
2089
  """
@@ -2114,7 +2138,7 @@ class _SyncSessions(SyncSessionsSugar):
2114
2138
  gemini: Union[models.GeminiConfig_Input, None] = None,
2115
2139
  idempotency_key: Union[str, None] = None,
2116
2140
  images: Union[List[models.ImageAttachment], None] = None,
2117
- metadata: Union[dict[str, str], None] = None,
2141
+ metadata: Union[models.ConfigMetadata_Input, None] = None,
2118
2142
  output: Union[models.OutputConfig, None] = None,
2119
2143
  permissions: Union[models.PermissionsConfig_Input, None] = None,
2120
2144
  skills: Union[List[models.SkillRef_Input], None] = None,
@@ -2875,7 +2899,7 @@ class Ellipsis:
2875
2899
  self,
2876
2900
  api_key: str,
2877
2901
  *,
2878
- base_url: str = DEFAULT_BASE_URL,
2902
+ base_url: str | None = None,
2879
2903
  timeout: float = DEFAULT_TIMEOUT_SECONDS,
2880
2904
  max_retries: int = MAX_RETRIES,
2881
2905
  ) -> None:
@@ -3650,10 +3674,13 @@ class _AsyncAgents:
3650
3674
 
3651
3675
  async def list(
3652
3676
  self,
3677
+ *,
3678
+ label: Union[List[str], None] = None,
3679
+ annotation: Union[List[str], None] = None,
3653
3680
  ) -> models.AgentsListResponse:
3654
3681
  """List Agents
3655
3682
 
3656
- List agents.
3683
+ List agents, optionally only those with the given labels and annotations.
3657
3684
 
3658
3685
  Required permissions: read:configs.
3659
3686
  API key: Supported.
@@ -3663,8 +3690,14 @@ class _AsyncAgents:
3663
3690
  Grant match patterns can further restrict access to individual resources.
3664
3691
  """
3665
3692
  path = "/v1/agents"
3693
+ query = build_query(
3694
+ {
3695
+ "label": label,
3696
+ "annotation": annotation,
3697
+ }
3698
+ )
3666
3699
  response = await self._transport.request(
3667
- "GET", path, response_model=models.AgentsListResponse
3700
+ "GET", path, response_model=models.AgentsListResponse, query=query
3668
3701
  )
3669
3702
  assert response is not None
3670
3703
  return response
@@ -3721,7 +3754,7 @@ class _AsyncAgents:
3721
3754
  idempotency_key: Union[str, None] = None,
3722
3755
  images: Union[List[models.ImageAttachment], None] = None,
3723
3756
  input: Union[dict[str, Any], None] = None,
3724
- metadata: Union[dict[str, Union[str, None]], None] = None,
3757
+ metadata: Union[models.ConfigMetadataPatch, None] = None,
3725
3758
  output: Union[models.OutputConfig, None] = None,
3726
3759
  permissions: Union[models.PermissionsConfig_Input, None] = None,
3727
3760
  skills: Union[List[models.SkillRef_Input], None] = None,
@@ -4098,10 +4131,13 @@ class _AsyncEnvironments:
4098
4131
 
4099
4132
  async def list(
4100
4133
  self,
4134
+ *,
4135
+ label: Union[List[str], None] = None,
4136
+ annotation: Union[List[str], None] = None,
4101
4137
  ) -> models.EnvironmentsListResponse:
4102
4138
  """List Environments
4103
4139
 
4104
- List saved environments.
4140
+ List saved environments, optionally only those with the given labels and annotations.
4105
4141
 
4106
4142
  Required permissions: read:environments.
4107
4143
  API key: Supported.
@@ -4110,8 +4146,14 @@ class _AsyncEnvironments:
4110
4146
  Higher permission levels include lower levels: read < write < delete.
4111
4147
  """
4112
4148
  path = "/v1/environments"
4149
+ query = build_query(
4150
+ {
4151
+ "label": label,
4152
+ "annotation": annotation,
4153
+ }
4154
+ )
4113
4155
  response = await self._transport.request(
4114
- "GET", path, response_model=models.EnvironmentsListResponse
4156
+ "GET", path, response_model=models.EnvironmentsListResponse, query=query
4115
4157
  )
4116
4158
  assert response is not None
4117
4159
  return response
@@ -4818,13 +4860,15 @@ class _AsyncSessions(AsyncSessionsSugar):
4818
4860
  author_id: Union[int, None] = None,
4819
4861
  repo: Union[str, None] = None,
4820
4862
  status: Union[List[models.SessionStatus], None] = None,
4863
+ label: Union[List[str], None] = None,
4864
+ annotation: Union[List[str], None] = None,
4821
4865
  ) -> AsyncPage[models.Session, models.SessionsListResponse]:
4822
4866
  """List Sessions
4823
4867
 
4824
4868
  List cloud agent sessions, newest first.
4825
4869
 
4826
4870
  Optionally filtered by agent (id or name), source, service, handler, time
4827
- window, attributed author, repository, and status.
4871
+ window, attributed author, repository, status, labels, and annotations.
4828
4872
 
4829
4873
  Required permissions: read:sessions.
4830
4874
  API key: Supported.
@@ -4848,6 +4892,8 @@ class _AsyncSessions(AsyncSessionsSugar):
4848
4892
  "author_id": author_id,
4849
4893
  "repo": repo,
4850
4894
  "status": status,
4895
+ "label": label,
4896
+ "annotation": annotation,
4851
4897
  }
4852
4898
  )
4853
4899
  response = await self._transport.request(
@@ -4870,6 +4916,8 @@ class _AsyncSessions(AsyncSessionsSugar):
4870
4916
  author_id=author_id,
4871
4917
  repo=repo,
4872
4918
  status=status,
4919
+ label=label,
4920
+ annotation=annotation,
4873
4921
  ),
4874
4922
  )
4875
4923
 
@@ -4956,14 +5004,15 @@ class _AsyncSessions(AsyncSessionsSugar):
4956
5004
  Send a message to a session.
4957
5005
 
4958
5006
  409 for mention, non-interactive, closed, archived, and
4959
- out-of-budget sessions. Returns the created message; a retried send with the
5007
+ out-of-budget sessions. 403 when a session token sends to its own
5008
+ session. Returns the created message; a retried send with the
4960
5009
  same idempotency_key returns the original one. The message is
4961
5010
  answered once the session's status is `idle` or `closed`.
4962
5011
 
4963
5012
  Required permissions: write:sessions.
4964
5013
  API key: Supported.
4965
5014
  CLI user token: Supported.
4966
- Session token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
5015
+ Session token: Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration. Never the token's own session.
4967
5016
  Higher permission levels include lower levels: read < write < delete.
4968
5017
  Grant match patterns can further restrict access to individual resources.
4969
5018
  """
@@ -5018,7 +5067,7 @@ class _AsyncSessions(AsyncSessionsSugar):
5018
5067
  gemini: Union[models.GeminiConfig_Input, None] = None,
5019
5068
  idempotency_key: Union[str, None] = None,
5020
5069
  images: Union[List[models.ImageAttachment], None] = None,
5021
- metadata: Union[dict[str, str], None] = None,
5070
+ metadata: Union[models.ConfigMetadata_Input, None] = None,
5022
5071
  output: Union[models.OutputConfig, None] = None,
5023
5072
  permissions: Union[models.PermissionsConfig_Input, None] = None,
5024
5073
  skills: Union[List[models.SkillRef_Input], None] = None,
@@ -5779,7 +5828,7 @@ class AsyncEllipsis:
5779
5828
  self,
5780
5829
  api_key: str,
5781
5830
  *,
5782
- base_url: str = DEFAULT_BASE_URL,
5831
+ base_url: str | None = None,
5783
5832
  timeout: float = DEFAULT_TIMEOUT_SECONDS,
5784
5833
  max_retries: int = MAX_RETRIES,
5785
5834
  ) -> None:
@@ -17,7 +17,7 @@ from urllib.parse import quote
17
17
 
18
18
  from . import frames
19
19
  from ._errors import EllipsisError
20
- from ._transport import DEFAULT_BASE_URL
20
+ from ._transport import resolve_base_url
21
21
 
22
22
  WS_CLOSE_NORMAL = 1000
23
23
  WS_CLOSE_AUTH_FAILED = 1008
@@ -146,7 +146,7 @@ async def stream_session(
146
146
  session_id: str,
147
147
  api_key: str,
148
148
  on_frame: Callable[[frames.StreamFrame], None | Awaitable[None]],
149
- base_url: str = DEFAULT_BASE_URL,
149
+ base_url: str | None = None,
150
150
  after_seq: int = 0,
151
151
  max_reconnects: int = DEFAULT_MAX_RECONNECTS,
152
152
  ) -> StreamOutcome:
@@ -164,6 +164,7 @@ async def stream_session(
164
164
  "the stream client needs the `websockets` package: pip install 'ellipsis-dev[stream]'"
165
165
  ) from exc
166
166
 
167
+ resolved_base_url = resolve_base_url(base_url)
167
168
  cursor = after_seq
168
169
  ever_received_frame = False
169
170
  attempt = 0
@@ -190,7 +191,7 @@ async def stream_session(
190
191
  failure = ""
191
192
  try:
192
193
  async with websockets.connect(
193
- _ws_url(base_url, session_id, cursor),
194
+ _ws_url(resolved_base_url, session_id, cursor),
194
195
  additional_headers={"Authorization": f"Bearer {api_key}"},
195
196
  ) as socket:
196
197
  while True:
@@ -5,6 +5,7 @@ calls `request()` with an operation's method/path/params/body and a response
5
5
  model; everything HTTP lives here.
6
6
  """
7
7
 
8
+ import os
8
9
  import random
9
10
  import time
10
11
  import uuid
@@ -17,6 +18,9 @@ from pydantic_core import to_jsonable_python
17
18
  from ._errors import APIError, TransportError, api_error_for
18
19
 
19
20
  DEFAULT_BASE_URL = "https://api.ellipsis.dev"
21
+ # Read when the caller passes no base_url. Session VMs set it, so code running
22
+ # inside a session reaches the API without configuration.
23
+ BASE_URL_ENV = "ELLIPSIS_API_BASE_URL"
20
24
  DEFAULT_TIMEOUT_SECONDS = 60.0
21
25
  # 429 and 5xx are retried with exponential backoff + jitter; everything else
22
26
  # raises immediately. Only idempotent-safe by the API's own semantics: every
@@ -64,6 +68,11 @@ def new_idempotency_key() -> str:
64
68
  return uuid.uuid4().hex
65
69
 
66
70
 
71
+ def resolve_base_url(base_url: str | None) -> str:
72
+ """The explicit base URL, else ELLIPSIS_API_BASE_URL, else the default."""
73
+ return (base_url or os.environ.get(BASE_URL_ENV) or DEFAULT_BASE_URL).rstrip("/")
74
+
75
+
67
76
  def _backoff_seconds(attempt: int, retry_after: str | None) -> float:
68
77
  if retry_after is not None:
69
78
  try:
@@ -80,13 +89,13 @@ class Transport:
80
89
  self,
81
90
  *,
82
91
  api_key: str,
83
- base_url: str = DEFAULT_BASE_URL,
92
+ base_url: str | None = None,
84
93
  timeout: float = DEFAULT_TIMEOUT_SECONDS,
85
94
  max_retries: int = MAX_RETRIES,
86
95
  ) -> None:
87
96
  self._max_retries = max_retries
88
97
  # Public so the stream client / sugar can reuse the credential.
89
- self.base_url = base_url.rstrip("/")
98
+ self.base_url = resolve_base_url(base_url)
90
99
  self.api_key = api_key
91
100
  self._client = httpx.Client(
92
101
  base_url=self.base_url,
@@ -132,12 +141,12 @@ class AsyncTransport:
132
141
  self,
133
142
  *,
134
143
  api_key: str,
135
- base_url: str = DEFAULT_BASE_URL,
144
+ base_url: str | None = None,
136
145
  timeout: float = DEFAULT_TIMEOUT_SECONDS,
137
146
  max_retries: int = MAX_RETRIES,
138
147
  ) -> None:
139
148
  self._max_retries = max_retries
140
- self.base_url = base_url.rstrip("/")
149
+ self.base_url = resolve_base_url(base_url)
141
150
  self.api_key = api_key
142
151
  self._client = httpx.AsyncClient(
143
152
  base_url=self.base_url,
@@ -165,8 +165,12 @@ class AccountSettings(EllipsisModel):
165
165
 
166
166
 
167
167
  class ConfigMetadata_Output(EllipsisModel):
168
- annotations: dict[str, str]
169
- labels: list[str]
168
+ """Labels and annotations for your own use, the same block on an agent, an environment, and a session. They never change how anything runs."""
169
+
170
+ annotations: dict[str, str] = Field(
171
+ description="String key/value pairs to tag and filter by. A key contains no `:`."
172
+ )
173
+ labels: list[str] = Field(description="Names to tag and filter by.")
170
174
 
171
175
 
172
176
  class AgentIdentity_Output(EllipsisModel):
@@ -926,8 +930,8 @@ class SessionConfig_Output(EllipsisModel):
926
930
  gemini: Union[GeminiConfig_Output, None] = Field(
927
931
  description="Gemini CLI input and native options. Set exactly one of claude_code, codex, or gemini."
928
932
  )
929
- metadata: dict[str, str] = Field(
930
- description="Arbitrary string key/value metadata stored on every session."
933
+ metadata: ConfigMetadata_Output = Field(
934
+ description="Labels and annotations stored on every session."
931
935
  )
932
936
  output: Union[OutputConfig, None]
933
937
  permissions: PermissionsConfig_Output
@@ -1044,8 +1048,15 @@ class Agent(EllipsisModel):
1044
1048
 
1045
1049
 
1046
1050
  class ConfigMetadata_Input(EllipsisModel):
1047
- annotations: Union[dict[str, str], None] = None
1048
- labels: Union[list[str], None] = None
1051
+ """Labels and annotations for your own use, the same block on an agent, an environment, and a session. They never change how anything runs."""
1052
+
1053
+ annotations: Union[dict[str, str], None] = Field(
1054
+ default=None,
1055
+ description="String key/value pairs to tag and filter by. A key contains no `:`.",
1056
+ )
1057
+ labels: Union[list[str], None] = Field(
1058
+ default=None, description="Names to tag and filter by."
1059
+ )
1049
1060
 
1050
1061
 
1051
1062
  class AgentIdentity_Input(EllipsisModel):
@@ -1686,9 +1697,8 @@ class SessionConfig_Input(EllipsisModel):
1686
1697
  default=None,
1687
1698
  description="Gemini CLI input and native options. Set exactly one of claude_code, codex, or gemini.",
1688
1699
  )
1689
- metadata: Union[dict[str, str], None] = Field(
1690
- default=None,
1691
- description="Arbitrary string key/value metadata stored on every session.",
1700
+ metadata: Union[ConfigMetadata_Input, None] = Field(
1701
+ default=None, description="Labels and annotations stored on every session."
1692
1702
  )
1693
1703
  output: Union[OutputConfig, None] = None
1694
1704
  permissions: Union[PermissionsConfig_Input, None] = None
@@ -3100,6 +3110,18 @@ class CodexSessionRecord(EllipsisRecord):
3100
3110
  tools: Union[list[str], None]
3101
3111
 
3102
3112
 
3113
+ class ConfigMetadataPatch(EllipsisModel):
3114
+ """Metadata merged into an agent's for one session."""
3115
+
3116
+ annotations: Union[dict[str, Union[str, None]], None] = Field(
3117
+ default=None,
3118
+ description="Each key you send sets that key, a `null` value removes the agent's key, and keys you leave out keep the agent's values.",
3119
+ )
3120
+ labels: Union[list[str], None] = Field(
3121
+ default=None, description="Labels added to the agent's."
3122
+ )
3123
+
3124
+
3103
3125
  class CreateAgentRequest(EllipsisModel):
3104
3126
  """Parameters for creating an agent."""
3105
3127
 
@@ -3964,7 +3986,7 @@ class IntegrationSessionConfig(EllipsisModel):
3964
3986
  default=None,
3965
3987
  description="Gemini CLI input and native options. Set exactly one of claude_code, codex, or gemini.",
3966
3988
  )
3967
- metadata: Union[dict[str, str], None] = None
3989
+ metadata: Union[ConfigMetadata_Output, None] = None
3968
3990
  permissions: Union[PermissionsConfig_Output, None] = None
3969
3991
  skills: Union[list[SkillRef_Output], None] = None
3970
3992
 
@@ -5715,8 +5737,8 @@ class Session(EllipsisModel):
5715
5737
  description="The saved handler and its effective display name when this session started, frozen at creation. Null for built-in responders, legacy sessions, and sessions started without a handler."
5716
5738
  )
5717
5739
  id: str = Field(description="Unique identifier of the session.")
5718
- metadata: dict[str, str] = Field(
5719
- description="Caller-supplied metadata key-value pairs."
5740
+ metadata: ConfigMetadata_Output = Field(
5741
+ description="Labels and annotations set when the session started."
5720
5742
  )
5721
5743
  output: Union[SessionOutput, None] = Field(
5722
5744
  description="The session's structured output: the `json_schema` the agent must satisfy and, once the agent has submitted it, the `result`."
@@ -5926,8 +5948,9 @@ class StartAgentSessionRequest(EllipsisModel):
5926
5948
  """Start a session from a saved agent. The body takes the fields of POST
5927
5949
  /v1/sessions, all optional, plus `input`. The session starts from the
5928
5950
  agent's `session` settings: each field you send replaces the agent's value for that field,
5929
- and each field you leave out keeps it. `metadata` is the exception: it is
5930
- merged into the agent's key by key, and a `null` value removes a key.
5951
+ and each field you leave out keeps it. `metadata` is the exception: its
5952
+ labels are added to the agent's, its annotations merge key by key, and a
5953
+ `null` annotation value removes a key.
5931
5954
  Other lists and maps, and `environment`, are replaced whole, and naming the
5932
5955
  other harness replaces the agent's harness. `input` is required when the
5933
5956
  agent declares `input.json_schema` and rejected when it doesn't. Extra keys
@@ -5974,9 +5997,9 @@ class StartAgentSessionRequest(EllipsisModel):
5974
5997
  default=None,
5975
5998
  description="The typed payload for an agent that declares input.json_schema. Required when the agent declares a schema; rejected when it does not. Validated against the schema and rendered through input.message, or as formatted JSON if no template is set, and added after the prompt. The rendered message must be non-empty.",
5976
5999
  )
5977
- metadata: Union[dict[str, Union[str, None]], None] = Field(
6000
+ metadata: Union[ConfigMetadataPatch, None] = Field(
5978
6001
  default=None,
5979
- description="Metadata merged into the agent's for this session. Each key you send sets that key, a `null` value removes the agent's key, and keys you leave out keep the agent's values.",
6002
+ description="Metadata merged into the agent's for this session. Labels you send are added to the agent's. Each annotation key you send sets that key, a `null` value removes the agent's key, and keys you leave out keep the agent's values.",
5980
6003
  )
5981
6004
  output: Union[OutputConfig, None] = Field(
5982
6005
  default=None,
@@ -6062,9 +6085,9 @@ class StartSessionRequest(EllipsisModel):
6062
6085
  default=None,
6063
6086
  description="Images attached to the first message, base64 inline. Requires the model's `images` capability, listed by `/v1/account/models`. Each becomes an `[Image #N]` placeholder in the prompt and an image block the model sees with it. Up to 10, 5 MiB each; PNG, JPEG, GIF, or WebP.",
6064
6087
  )
6065
- metadata: Union[dict[str, str], None] = Field(
6088
+ metadata: Union[ConfigMetadata_Input, None] = Field(
6066
6089
  default=None,
6067
- description="Arbitrary string key/value metadata stored on the session.",
6090
+ description="Labels and annotations stored on the session, to filter sessions by.",
6068
6091
  )
6069
6092
  output: Union[OutputConfig, None] = Field(
6070
6093
  default=None,
@@ -6462,6 +6485,7 @@ __all__ = [
6462
6485
  "ConfigManagedBy",
6463
6486
  "ConfigMetadata_Input",
6464
6487
  "ConfigMetadata_Output",
6488
+ "ConfigMetadataPatch",
6465
6489
  "ConfigSpendWindow",
6466
6490
  "ConfigUsageBucket",
6467
6491
  "Cost",
File without changes
File without changes