archastro.platform.v1.resources.agent_sessions

  1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: 87b5e0da34ba
  4
  5from __future__ import annotations
  6
  7import builtins
  8from collections.abc import AsyncIterator, Iterator
  9from typing import Any, Literal, Required, TypedDict
 10
 11from ...runtime.http_client import HttpClient, SyncHttpClient
 12from ...types.common import AgentSession, AgentSessionListResponse
 13
 14
 15class AgentSessionCreateInput(TypedDict, total=False):
 16    "Create an agent session"
 17
 18    agent: Required[str]
 19    "Agent ID (`agi_...`) of the agent that will execute the session."
 20    instructions: Required[str]
 21    "Plain-text task description given to the agent as its primary objective for this session."
 22    max_runs_per_turn: int | None
 23    "Maximum number of tool invocations allowed within a single agent turn. Defaults to 25."
 24    max_tokens: int | None
 25    "Maximum number of tokens the agent may consume across all turns. Defaults to 20,000."
 26    max_turns: int | None
 27    "Maximum number of agent turns before the session is automatically terminated. Defaults to 100."
 28    metadata: dict[str, Any] | None
 29    "Arbitrary key-value metadata to attach to the session. Stored and returned as-is; not interpreted by the platform."
 30    name: str | None
 31    "Human-readable display name for the session. Useful for identifying sessions in the dashboard. `null` if omitted."
 32    start_idle: bool | None
 33    'When `true`, create the session without running an opening turn. The session starts in `"waiting"` status and runs its first turn only when you post a message. Defaults to `false`, which runs an initial turn from `instructions` immediately.'
 34    team: str | None
 35    "Team ID (`tea_...`) to associate with this session for access-control and attribution purposes. `null` if omitted."
 36    thread: str | None
 37    "Thread ID (`thr_...`) to link this session to an existing conversation thread. `null` if omitted."
 38    user: str | None
 39    "User ID to associate with this session for attribution purposes. `null` if omitted."
 40
 41
 42class AgentSessionUpdateInput(TypedDict, total=False):
 43    "Update an agent session"
 44
 45    metadata: dict[str, Any] | None
 46    "Arbitrary key-value metadata to attach to the session. Replaces the existing metadata map entirely. Omit to leave the current metadata unchanged."
 47
 48
 49class AgentSessionMessageInput(TypedDict, total=False):
 50    "Send a message to an agent session"
 51
 52    content: Required[str]
 53    "Plain-text body of the message to deliver to the agent."
 54    metadata: dict[str, Any] | None
 55    "Arbitrary key-value metadata to attach to the message. Stored and returned as-is; not interpreted by the platform."
 56    role: str | None
 57    'Role of the message sender. Typically `"user"` or `"tool"`. Defaults to `"user"`.'
 58
 59
 60class AgentSessionStreamEventSessionUpdate(TypedDict):
 61    event: Literal["session_update"]
 62    data: AgentSession
 63
 64
 65AgentSessionStreamEvent = AgentSessionStreamEventSessionUpdate
 66
 67
 68class AsyncAgentSessionResource:
 69    def __init__(self, http: HttpClient):
 70        self._http = http
 71
 72    async def list(
 73        self,
 74        *,
 75        agent: builtins.list[str] | None = None,
 76        status: builtins.list[str] | None = None,
 77        routine_run: builtins.list[str] | None = None,
 78        exclude_system: bool | None = None,
 79        limit: int | None = None,
 80    ) -> AgentSessionListResponse:
 81        """
 82        List agent sessions
 83        Returns a flat list of agent sessions visible to the authenticated app,
 84        ordered by creation time descending. Use the `agent`, `status`, and
 85        `routine_run` filters to narrow results.
 86        All filters are optional and can be combined. The `status` and `routine_run`
 87        parameters each accept multiple values; pass the parameter more than once or
 88        as a comma-separated array to match any of the supplied values.
 89        Requires an app-scoped API key. Results are limited to sessions that belong
 90        to agents owned by the authenticated app.
 91
 92        Args:
 93            agent: Filter by agent IDs (`agi_...`). Omit to return sessions for all agents in the app. Multiple values are OR'd.
 94            status: Filter by one or more session statuses. Accepted values are `"pending"`, `"running"`, `"waiting"`, `"completed"`, `"failed"`, and `"cancelled"`. Omit to return sessions in any status.
 95            routine_run: Filter to sessions that were created by the specified routine run IDs. Accepts up to 100 IDs. Omit to return sessions regardless of their originating routine run.
 96            exclude_system: When `true`, omits sessions that were created automatically by the platform rather than by your app. Defaults to `false`.
 97            limit: Maximum number of sessions to return. Defaults to 25; maximum is 100.
 98
 99        Returns:
100            A list of agent sessions matching the supplied filters.
101        """
102        query: dict[str, object] = {}
103        if agent is not None:
104            query["agent"] = agent
105        if status is not None:
106            query["status"] = status
107        if routine_run is not None:
108            query["routine_run"] = routine_run
109        if exclude_system is not None:
110            query["exclude_system"] = exclude_system
111        if limit is not None:
112            query["limit"] = limit
113        return await self._http.request(
114            "/api/v1/agent_sessions",
115            query=query,
116            response_type=AgentSessionListResponse,
117        )
118
119    async def create(self, input: AgentSessionCreateInput) -> AgentSession:
120        """
121        Create an agent session
122        Creates a new agent session and enqueues it for execution. The session begins
123        in `"pending"` status and transitions to `"running"` once the platform picks
124        it up. Subscribe to the session stream endpoint to receive real-time status
125        updates.
126        You must supply the ID of an agent that the authenticated app owns and a
127        plain-text `instructions` string describing the task. All other parameters
128        are optional and default to the agent's configured limits when omitted.
129        Set `start_idle` to `true` to create the session without running an opening
130        turn it begins in `"waiting"` status and runs its first turn only once you
131        post a message (see the message endpoint). Use this when you want the first
132        message to drive the session instead of the `instructions` alone.
133        Requires an app-scoped API key. Returns HTTP 201 on success.
134
135        Args:
136            input: Request body.
137            input.agent: Agent ID (`agi_...`) of the agent that will execute the session.
138            input.instructions: Plain-text task description given to the agent as its primary objective for this session.
139            input.max_runs_per_turn: Maximum number of tool invocations allowed within a single agent turn. Defaults to 25.
140            input.max_tokens: Maximum number of tokens the agent may consume across all turns. Defaults to 20,000.
141            input.max_turns: Maximum number of agent turns before the session is automatically terminated. Defaults to 100.
142            input.metadata: Arbitrary key-value metadata to attach to the session. Stored and returned as-is; not interpreted by the platform.
143            input.name: Human-readable display name for the session. Useful for identifying sessions in the dashboard. `null` if omitted.
144            input.start_idle: When `true`, create the session without running an opening turn. The session starts in `"waiting"` status and runs its first turn only when you post a message. Defaults to `false`, which runs an initial turn from `instructions` immediately.
145            input.team: Team ID (`tea_...`) to associate with this session for access-control and attribution purposes. `null` if omitted.
146            input.thread: Thread ID (`thr_...`) to link this session to an existing conversation thread. `null` if omitted.
147            input.user: User ID to associate with this session for attribution purposes. `null` if omitted.
148
149        Returns:
150            The newly created agent session.
151        """
152        return await self._http.request(
153            "/api/v1/agent_sessions",
154            method="POST",
155            body=input,
156            response_type=AgentSession,
157        )
158
159    async def delete(self, agent_session: str) -> None:
160        """
161        Delete an agent session
162        Permanently deletes an agent session and its associated data. This action is
163        irreversible the session record, its trajectory, and all inbox messages are
164        removed.
165        To stop a running session without deleting it, use the cancel endpoint
166        instead. The session must be in a terminal state (`"completed"`, `"failed"`,
167        or `"cancelled"`) before it can be deleted; attempting to delete an active
168        session returns 422.
169        Requires an app-scoped API key. Returns HTTP 204 with no body on success.
170
171        Args:
172            agent_session: Agent session ID (`ase_...`) of the session to delete.
173
174        Returns:
175            Empty body. HTTP 204 indicates the session was permanently deleted.
176        """
177        await self._http.request(f"/api/v1/agent_sessions/{agent_session}", method="DELETE")
178
179    async def get(self, agent_session: str) -> AgentSession:
180        """
181        Retrieve an agent session
182        Returns the agent session identified by `agent_session`. Use this endpoint
183        to poll session status or to inspect the final result after execution
184        completes.
185        For real-time updates without polling, subscribe to the session stream
186        endpoint instead, which delivers server-sent events whenever the session
187        state changes.
188        Requires an app-scoped API key. The session must belong to an agent owned
189        by the authenticated app.
190
191        Args:
192            agent_session: Agent session ID (`ase_...`) of the session to retrieve.
193
194        Returns:
195            The requested agent session.
196        """
197        return await self._http.request(
198            f"/api/v1/agent_sessions/{agent_session}",
199            response_type=AgentSession,
200        )
201
202    async def update(self, agent_session: str, input: AgentSessionUpdateInput) -> AgentSession:
203        """
204        Update an agent session
205        Updates the mutable fields of an agent session. Currently only `metadata`
206        can be changed; supply any key-value pairs you want to store alongside the
207        session. Omitting `metadata` leaves it unchanged.
208        This endpoint may be called while the session is in any status, including
209        while it is actively running.
210        Requires an app-scoped API key. The session must belong to an agent owned
211        by the authenticated app.
212
213        Args:
214            agent_session: Agent session ID (`ase_...`) of the session to update.
215            input: Request body.
216            input.metadata: Arbitrary key-value metadata to attach to the session. Replaces the existing metadata map entirely. Omit to leave the current metadata unchanged.
217
218        Returns:
219            The agent session with the updated fields applied.
220        """
221        return await self._http.request(
222            f"/api/v1/agent_sessions/{agent_session}",
223            method="PATCH",
224            body=input,
225            response_type=AgentSession,
226        )
227
228    async def cancel(self, agent_session: str) -> AgentSession:
229        """
230        Cancel an agent session
231        Requests cancellation of an active agent session. The session status is set
232        to `"cancelled"` and any in-progress agent turn is interrupted as soon as the
233        platform can safely stop it.
234        If the session is already in a terminal state (`"completed"`, `"failed"`, or
235        `"cancelled"`), the call succeeds and returns the session unchanged it is
236        safe to call this endpoint more than once.
237        Requires an app-scoped API key. The session must belong to an agent owned by
238        the authenticated app.
239
240        Args:
241            agent_session: Agent session ID (`ase_...`) of the session to cancel.
242
243        Returns:
244            The agent session after the cancellation request is applied.
245        """
246        return await self._http.request(
247            f"/api/v1/agent_sessions/{agent_session}/cancel",
248            method="POST",
249            response_type=AgentSession,
250        )
251
252    async def message(self, agent_session: str, input: AgentSessionMessageInput) -> AgentSession:
253        """
254        Send a message to an agent session
255        Appends a message to the inbox of the specified agent session. The agent
256        reads inbox messages at the start of each turn; sending a message to a
257        `"waiting"` session signals it to resume execution.
258        Use `role` to identify the sender type. The default role is `"user"`.
259        Arbitrary key-value metadata may be attached to the message for tracking
260        or display purposes.
261        Requires an app-scoped API key. The session must belong to an agent owned
262        by the authenticated app.
263
264        Args:
265            agent_session: Agent session ID (`ase_...`) of the session whose inbox should receive the message.
266            input: Request body.
267            input.content: Plain-text body of the message to deliver to the agent.
268            input.metadata: Arbitrary key-value metadata to attach to the message. Stored and returned as-is; not interpreted by the platform.
269            input.role: Role of the message sender. Typically `"user"` or `"tool"`. Defaults to `"user"`.
270
271        Returns:
272            The agent session with the new message appended to its `inbox`.
273        """
274        return await self._http.request(
275            f"/api/v1/agent_sessions/{agent_session}/message",
276            method="POST",
277            body=input,
278            response_type=AgentSession,
279        )
280
281    async def stream(self, agent_session: str) -> AsyncIterator[AgentSessionStreamEvent]:
282        """
283        Stream agent session status
284        Opens a Server-Sent Events connection that emits a `session_update` event
285        whenever the agent session's status changes, replaying the current status on
286        connect and closing on a terminal status (`completed`, `failed`, `cancelled`).
287
288        Args:
289            agent_session: ID of the agent session to stream.
290
291        Returns:
292            Server-Sent Events stream
293        """
294        async for event in self._http.stream_sse(f"/api/v1/agent_sessions/{agent_session}/stream"):
295            yield event
296
297
298class AgentSessionResource:
299    def __init__(self, http: SyncHttpClient):
300        self._http = http
301
302    def list(
303        self,
304        *,
305        agent: builtins.list[str] | None = None,
306        status: builtins.list[str] | None = None,
307        routine_run: builtins.list[str] | None = None,
308        exclude_system: bool | None = None,
309        limit: int | None = None,
310    ) -> AgentSessionListResponse:
311        """
312        List agent sessions
313        Returns a flat list of agent sessions visible to the authenticated app,
314        ordered by creation time descending. Use the `agent`, `status`, and
315        `routine_run` filters to narrow results.
316        All filters are optional and can be combined. The `status` and `routine_run`
317        parameters each accept multiple values; pass the parameter more than once or
318        as a comma-separated array to match any of the supplied values.
319        Requires an app-scoped API key. Results are limited to sessions that belong
320        to agents owned by the authenticated app.
321
322        Args:
323            agent: Filter by agent IDs (`agi_...`). Omit to return sessions for all agents in the app. Multiple values are OR'd.
324            status: Filter by one or more session statuses. Accepted values are `"pending"`, `"running"`, `"waiting"`, `"completed"`, `"failed"`, and `"cancelled"`. Omit to return sessions in any status.
325            routine_run: Filter to sessions that were created by the specified routine run IDs. Accepts up to 100 IDs. Omit to return sessions regardless of their originating routine run.
326            exclude_system: When `true`, omits sessions that were created automatically by the platform rather than by your app. Defaults to `false`.
327            limit: Maximum number of sessions to return. Defaults to 25; maximum is 100.
328
329        Returns:
330            A list of agent sessions matching the supplied filters.
331        """
332        query: dict[str, object] = {}
333        if agent is not None:
334            query["agent"] = agent
335        if status is not None:
336            query["status"] = status
337        if routine_run is not None:
338            query["routine_run"] = routine_run
339        if exclude_system is not None:
340            query["exclude_system"] = exclude_system
341        if limit is not None:
342            query["limit"] = limit
343        return self._http.request(
344            "/api/v1/agent_sessions",
345            query=query,
346            response_type=AgentSessionListResponse,
347        )
348
349    def create(self, input: AgentSessionCreateInput) -> AgentSession:
350        """
351        Create an agent session
352        Creates a new agent session and enqueues it for execution. The session begins
353        in `"pending"` status and transitions to `"running"` once the platform picks
354        it up. Subscribe to the session stream endpoint to receive real-time status
355        updates.
356        You must supply the ID of an agent that the authenticated app owns and a
357        plain-text `instructions` string describing the task. All other parameters
358        are optional and default to the agent's configured limits when omitted.
359        Set `start_idle` to `true` to create the session without running an opening
360        turn it begins in `"waiting"` status and runs its first turn only once you
361        post a message (see the message endpoint). Use this when you want the first
362        message to drive the session instead of the `instructions` alone.
363        Requires an app-scoped API key. Returns HTTP 201 on success.
364
365        Args:
366            input: Request body.
367            input.agent: Agent ID (`agi_...`) of the agent that will execute the session.
368            input.instructions: Plain-text task description given to the agent as its primary objective for this session.
369            input.max_runs_per_turn: Maximum number of tool invocations allowed within a single agent turn. Defaults to 25.
370            input.max_tokens: Maximum number of tokens the agent may consume across all turns. Defaults to 20,000.
371            input.max_turns: Maximum number of agent turns before the session is automatically terminated. Defaults to 100.
372            input.metadata: Arbitrary key-value metadata to attach to the session. Stored and returned as-is; not interpreted by the platform.
373            input.name: Human-readable display name for the session. Useful for identifying sessions in the dashboard. `null` if omitted.
374            input.start_idle: When `true`, create the session without running an opening turn. The session starts in `"waiting"` status and runs its first turn only when you post a message. Defaults to `false`, which runs an initial turn from `instructions` immediately.
375            input.team: Team ID (`tea_...`) to associate with this session for access-control and attribution purposes. `null` if omitted.
376            input.thread: Thread ID (`thr_...`) to link this session to an existing conversation thread. `null` if omitted.
377            input.user: User ID to associate with this session for attribution purposes. `null` if omitted.
378
379        Returns:
380            The newly created agent session.
381        """
382        return self._http.request(
383            "/api/v1/agent_sessions",
384            method="POST",
385            body=input,
386            response_type=AgentSession,
387        )
388
389    def delete(self, agent_session: str) -> None:
390        """
391        Delete an agent session
392        Permanently deletes an agent session and its associated data. This action is
393        irreversible the session record, its trajectory, and all inbox messages are
394        removed.
395        To stop a running session without deleting it, use the cancel endpoint
396        instead. The session must be in a terminal state (`"completed"`, `"failed"`,
397        or `"cancelled"`) before it can be deleted; attempting to delete an active
398        session returns 422.
399        Requires an app-scoped API key. Returns HTTP 204 with no body on success.
400
401        Args:
402            agent_session: Agent session ID (`ase_...`) of the session to delete.
403
404        Returns:
405            Empty body. HTTP 204 indicates the session was permanently deleted.
406        """
407        self._http.request(f"/api/v1/agent_sessions/{agent_session}", method="DELETE")
408
409    def get(self, agent_session: str) -> AgentSession:
410        """
411        Retrieve an agent session
412        Returns the agent session identified by `agent_session`. Use this endpoint
413        to poll session status or to inspect the final result after execution
414        completes.
415        For real-time updates without polling, subscribe to the session stream
416        endpoint instead, which delivers server-sent events whenever the session
417        state changes.
418        Requires an app-scoped API key. The session must belong to an agent owned
419        by the authenticated app.
420
421        Args:
422            agent_session: Agent session ID (`ase_...`) of the session to retrieve.
423
424        Returns:
425            The requested agent session.
426        """
427        return self._http.request(
428            f"/api/v1/agent_sessions/{agent_session}",
429            response_type=AgentSession,
430        )
431
432    def update(self, agent_session: str, input: AgentSessionUpdateInput) -> AgentSession:
433        """
434        Update an agent session
435        Updates the mutable fields of an agent session. Currently only `metadata`
436        can be changed; supply any key-value pairs you want to store alongside the
437        session. Omitting `metadata` leaves it unchanged.
438        This endpoint may be called while the session is in any status, including
439        while it is actively running.
440        Requires an app-scoped API key. The session must belong to an agent owned
441        by the authenticated app.
442
443        Args:
444            agent_session: Agent session ID (`ase_...`) of the session to update.
445            input: Request body.
446            input.metadata: Arbitrary key-value metadata to attach to the session. Replaces the existing metadata map entirely. Omit to leave the current metadata unchanged.
447
448        Returns:
449            The agent session with the updated fields applied.
450        """
451        return self._http.request(
452            f"/api/v1/agent_sessions/{agent_session}",
453            method="PATCH",
454            body=input,
455            response_type=AgentSession,
456        )
457
458    def cancel(self, agent_session: str) -> AgentSession:
459        """
460        Cancel an agent session
461        Requests cancellation of an active agent session. The session status is set
462        to `"cancelled"` and any in-progress agent turn is interrupted as soon as the
463        platform can safely stop it.
464        If the session is already in a terminal state (`"completed"`, `"failed"`, or
465        `"cancelled"`), the call succeeds and returns the session unchanged it is
466        safe to call this endpoint more than once.
467        Requires an app-scoped API key. The session must belong to an agent owned by
468        the authenticated app.
469
470        Args:
471            agent_session: Agent session ID (`ase_...`) of the session to cancel.
472
473        Returns:
474            The agent session after the cancellation request is applied.
475        """
476        return self._http.request(
477            f"/api/v1/agent_sessions/{agent_session}/cancel",
478            method="POST",
479            response_type=AgentSession,
480        )
481
482    def message(self, agent_session: str, input: AgentSessionMessageInput) -> AgentSession:
483        """
484        Send a message to an agent session
485        Appends a message to the inbox of the specified agent session. The agent
486        reads inbox messages at the start of each turn; sending a message to a
487        `"waiting"` session signals it to resume execution.
488        Use `role` to identify the sender type. The default role is `"user"`.
489        Arbitrary key-value metadata may be attached to the message for tracking
490        or display purposes.
491        Requires an app-scoped API key. The session must belong to an agent owned
492        by the authenticated app.
493
494        Args:
495            agent_session: Agent session ID (`ase_...`) of the session whose inbox should receive the message.
496            input: Request body.
497            input.content: Plain-text body of the message to deliver to the agent.
498            input.metadata: Arbitrary key-value metadata to attach to the message. Stored and returned as-is; not interpreted by the platform.
499            input.role: Role of the message sender. Typically `"user"` or `"tool"`. Defaults to `"user"`.
500
501        Returns:
502            The agent session with the new message appended to its `inbox`.
503        """
504        return self._http.request(
505            f"/api/v1/agent_sessions/{agent_session}/message",
506            method="POST",
507            body=input,
508            response_type=AgentSession,
509        )
510
511    def stream(self, agent_session: str) -> Iterator[AgentSessionStreamEvent]:
512        """
513        Stream agent session status
514        Opens a Server-Sent Events connection that emits a `session_update` event
515        whenever the agent session's status changes, replaying the current status on
516        connect and closing on a terminal status (`completed`, `failed`, `cancelled`).
517
518        Args:
519            agent_session: ID of the agent session to stream.
520
521        Returns:
522            Server-Sent Events stream
523        """
524        yield from self._http.stream_sse_sync(f"/api/v1/agent_sessions/{agent_session}/stream")