archastro.platform.v1.resources.agent_sessions

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