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