archastro.platform.v1.resources.agent_routine_runs

  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: 0e7cf4cc9657
  4
  5from __future__ import annotations
  6
  7import builtins
  8from collections.abc import AsyncIterator, Iterator
  9from typing import Literal, TypedDict
 10
 11from ...runtime.http_client import HttpClient, SyncHttpClient
 12from ...types.common import AgentRoutineRun, AgentRoutineRunListResponse
 13
 14
 15class AgentRoutineRunStreamEventRunUpdate(TypedDict):
 16    event: Literal["run_update"]
 17    data: AgentRoutineRun
 18
 19
 20AgentRoutineRunStreamEvent = AgentRoutineRunStreamEventRunUpdate
 21
 22
 23class AsyncAgentRoutineRunResource:
 24    def __init__(self, http: HttpClient):
 25        self._http = http
 26
 27    async def list(
 28        self,
 29        *,
 30        agent: builtins.list[str] | None = None,
 31        status: str | None = None,
 32        limit: int | None = None,
 33        before_cursor: str | None = None,
 34        after_cursor: str | None = None,
 35    ) -> AgentRoutineRunListResponse:
 36        """
 37        List agent routine runs
 38        Returns a paginated list of agent routine runs across all routines visible to
 39        the authenticated app scope. Results are ordered by creation time descending
 40        (most recent first).
 41        Use the `agent` parameter to filter runs to one or more specific agents. Use
 42        `status` to narrow results to runs in a particular state. Pagination is
 43        bidirectional: supply `after_cursor` to page forward through newer runs or
 44        `before_cursor` to page backward through older runs.
 45        This endpoint requires an app scope. Requests without a valid app credential
 46        return 403.
 47
 48        Args:
 49            agent: Filter by one or more agent IDs (`agi_...`) or `lookup_key` values. Repeat the parameter (e.g. `?agent[]=agi_a&agent[]=agi_b`) to OR multiple agents. Omit to return runs for all agents.
 50            status: Filter by run status. One of `"pending"`, `"running"`, `"completed"`, `"failed"`, `"skipped"`, or `"cancelled"`. Omit to return runs in any status.
 51            limit: Maximum number of runs to return. Defaults to 50; maximum is 100.
 52            before_cursor: Opaque cursor from a previous response's `before_cursor` field. Returns the page of runs older than that cursor position.
 53            after_cursor: Opaque cursor from a previous response's `after_cursor` field. Returns the page of runs newer than that cursor position.
 54
 55        Returns:
 56            Paginated list of agent routine runs.
 57        """
 58        query: dict[str, object] = {}
 59        if agent is not None:
 60            query["agent"] = agent
 61        if status is not None:
 62            query["status"] = status
 63        if limit is not None:
 64            query["limit"] = limit
 65        if before_cursor is not None:
 66            query["before_cursor"] = before_cursor
 67        if after_cursor is not None:
 68            query["after_cursor"] = after_cursor
 69        return await self._http.request(
 70            "/api/v1/agent_routine_runs",
 71            query=query,
 72            response_type=AgentRoutineRunListResponse,
 73        )
 74
 75    async def stream(self, agent_routine_run: str) -> AsyncIterator[AgentRoutineRunStreamEvent]:
 76        """
 77        Stream agent routine run status
 78        Opens a long-lived Server-Sent Events connection that emits a `run_update`
 79        event whenever the routine run's status changes, replaying the current status
 80        immediately on connect. The stream closes when the run reaches a terminal
 81        status (`completed`, `failed`, `skipped`, `cancelled`) or the maximum stream
 82        duration elapses (a terminal `error` event with `stream_timeout` is sent).
 83        Keepalive comments are emitted on an interval to hold the connection open.
 84
 85        Args:
 86            agent_routine_run: ID of the agent routine run to stream status updates for.
 87
 88        Returns:
 89            Server-Sent Events stream
 90        """
 91        async for event in self._http.stream_sse(
 92            f"/api/v1/agent_routine_runs/{agent_routine_run}/stream"
 93        ):
 94            yield event
 95
 96
 97class AgentRoutineRunResource:
 98    def __init__(self, http: SyncHttpClient):
 99        self._http = http
100
101    def list(
102        self,
103        *,
104        agent: builtins.list[str] | None = None,
105        status: str | None = None,
106        limit: int | None = None,
107        before_cursor: str | None = None,
108        after_cursor: str | None = None,
109    ) -> AgentRoutineRunListResponse:
110        """
111        List agent routine runs
112        Returns a paginated list of agent routine runs across all routines visible to
113        the authenticated app scope. Results are ordered by creation time descending
114        (most recent first).
115        Use the `agent` parameter to filter runs to one or more specific agents. Use
116        `status` to narrow results to runs in a particular state. Pagination is
117        bidirectional: supply `after_cursor` to page forward through newer runs or
118        `before_cursor` to page backward through older runs.
119        This endpoint requires an app scope. Requests without a valid app credential
120        return 403.
121
122        Args:
123            agent: Filter by one or more agent IDs (`agi_...`) or `lookup_key` values. Repeat the parameter (e.g. `?agent[]=agi_a&agent[]=agi_b`) to OR multiple agents. Omit to return runs for all agents.
124            status: Filter by run status. One of `"pending"`, `"running"`, `"completed"`, `"failed"`, `"skipped"`, or `"cancelled"`. Omit to return runs in any status.
125            limit: Maximum number of runs to return. Defaults to 50; maximum is 100.
126            before_cursor: Opaque cursor from a previous response's `before_cursor` field. Returns the page of runs older than that cursor position.
127            after_cursor: Opaque cursor from a previous response's `after_cursor` field. Returns the page of runs newer than that cursor position.
128
129        Returns:
130            Paginated list of agent routine runs.
131        """
132        query: dict[str, object] = {}
133        if agent is not None:
134            query["agent"] = agent
135        if status is not None:
136            query["status"] = status
137        if limit is not None:
138            query["limit"] = limit
139        if before_cursor is not None:
140            query["before_cursor"] = before_cursor
141        if after_cursor is not None:
142            query["after_cursor"] = after_cursor
143        return self._http.request(
144            "/api/v1/agent_routine_runs",
145            query=query,
146            response_type=AgentRoutineRunListResponse,
147        )
148
149    def stream(self, agent_routine_run: str) -> Iterator[AgentRoutineRunStreamEvent]:
150        """
151        Stream agent routine run status
152        Opens a long-lived Server-Sent Events connection that emits a `run_update`
153        event whenever the routine run's status changes, replaying the current status
154        immediately on connect. The stream closes when the run reaches a terminal
155        status (`completed`, `failed`, `skipped`, `cancelled`) or the maximum stream
156        duration elapses (a terminal `error` event with `stream_timeout` is sent).
157        Keepalive comments are emitted on an interval to hold the connection open.
158
159        Args:
160            agent_routine_run: ID of the agent routine run to stream status updates for.
161
162        Returns:
163            Server-Sent Events stream
164        """
165        yield from self._http.stream_sse_sync(
166            f"/api/v1/agent_routine_runs/{agent_routine_run}/stream"
167        )