archastro.platform.v1.resources.agent_routines

  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: 4f81edf1b7af
  4
  5from __future__ import annotations
  6
  7import builtins
  8from typing import Any, Literal, Required, TypedDict
  9
 10from ...runtime.http_client import HttpClient, SyncHttpClient
 11from ...types.common import (
 12    AgentRoutine,
 13    AgentRoutineListResponse,
 14    AgentRoutineRun,
 15    AgentRoutineRunListResponse,
 16    RoutinePreset,
 17    RunJournalPage,
 18)
 19
 20
 21class AgentRoutineUpdateInputAclAddItem(TypedDict, total=False):
 22    actions: Required[list[str]]
 23    'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.'
 24    principal: str | None
 25    'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.'
 26    principal_type: Required[str]
 27    'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
 28
 29
 30class AgentRoutineUpdateInputAclGrantsItem(TypedDict, total=False):
 31    actions: Required[list[str]]
 32    'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.'
 33    principal: str | None
 34    'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.'
 35    principal_type: Required[str]
 36    'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
 37
 38
 39class AgentRoutineUpdateInputAclRemoveItem(TypedDict, total=False):
 40    principal: str | None
 41    'The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.'
 42    principal_type: Required[str]
 43    'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
 44
 45
 46class AgentRoutineUpdateInputAcl(TypedDict, total=False):
 47    add: list[AgentRoutineUpdateInputAclAddItem] | None
 48    "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`."
 49    grants: list[AgentRoutineUpdateInputAclGrantsItem] | None
 50    "Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`."
 51    remove: list[AgentRoutineUpdateInputAclRemoveItem] | None
 52    "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`."
 53
 54
 55class AgentRoutineUpdateInputMessagePolicy(TypedDict, total=False):
 56    recipients: list[str] | None
 57    "Required and non-empty for private visibility. Sources are additive. Routine owner includes the agent owner and optional user co-owner."
 58    visibility: str | None
 59    "Message visibility. One of `default` or `private`."
 60
 61
 62class AgentRoutineUpdateInputPresetConfigLlm(TypedDict, total=False):
 63    model: str | None
 64    'Provider-prefixed model identifier for this routine or step, e.g. `"openrouter/anthropic/claude-sonnet-latest"`. When omitted, the agent\'s default model is used.'
 65
 66
 67class AgentRoutineUpdateInputPresetConfig(TypedDict, total=False):
 68    instructions: str | None
 69    "Custom task or behavior instructions for the preset (max 10,000 chars)."
 70    llm: AgentRoutineUpdateInputPresetConfigLlm | None
 71    "LLM invocation settings (e.g. a `model` override for this routine/step)."
 72    session_mode: str | None
 73    "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`)."
 74    session_scope: str | None
 75    "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`."
 76    structured_message_template_ids: list[str] | None
 77    "IDs of structured message templates that constrain the agent's responses to predefined structured formats."
 78
 79
 80class AgentRoutineUpdateInputStepsItemPresetConfigLlm(TypedDict, total=False):
 81    model: str | None
 82    'Provider-prefixed model identifier for this routine or step, e.g. `"openrouter/anthropic/claude-sonnet-latest"`. When omitted, the agent\'s default model is used.'
 83
 84
 85class AgentRoutineUpdateInputStepsItemPresetConfig(TypedDict, total=False):
 86    instructions: str | None
 87    "Custom task or behavior instructions for the preset (max 10,000 chars)."
 88    llm: AgentRoutineUpdateInputStepsItemPresetConfigLlm | None
 89    "LLM invocation settings (e.g. a `model` override for this routine/step)."
 90    session_mode: str | None
 91    "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`)."
 92    session_scope: str | None
 93    "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`."
 94    structured_message_template_ids: list[str] | None
 95    "IDs of structured message templates that constrain the agent's responses to predefined structured formats."
 96
 97
 98class AgentRoutineUpdateInputStepsItem(TypedDict, total=False):
 99    config: str | None
100    'ID of a saved config to use as the handler body. Required when `handler_type` is `"workflow_graph"`; also accepted for `"script"` as an alternative to an inline `script` value.'
101    handler_type: Required[str]
102    'Execution handler for this step. One of `"preset"`, `"script"`, or `"workflow_graph"`.'
103    inputs: dict[str, Any] | None
104    "Optional key-value map binding outputs from prior steps to this step's input variables."
105    name: str | None
106    "Optional label for this step. Must be unique within the chain when provided."
107    on_error: str | None
108    'Error handling policy for this step. One of `"halt"` (default), `"continue"`, or `"retry"`.'
109    output_key: str | None
110    "Key under which this step's result is stored and addressable by downstream steps. Defaults to `name` when omitted."
111    preset_config: AgentRoutineUpdateInputStepsItemPresetConfig | None
112    "Configuration overrides for the preset, using the same shape as the routine-level `preset_config`. You may include an `llm` key to override the agent's default model for this step. `null` if not provided."
113    preset_name: str | None
114    'Name of the preset to invoke. Required when `handler_type` is `"preset"`.'
115    script: str | None
116    'Inline script source code to execute. Used when `handler_type` is `"script"` and no `config` is provided.'
117
118
119class AgentRoutineUpdateInput(TypedDict, total=False):
120    "Update a routine"
121
122    acl: AgentRoutineUpdateInputAcl | None
123    "Updated access control list. Replaces the existing ACL entirely."
124    config: str | None
125    'Workflow config ID (`cfg_...`). Used when `handler_type` is `"workflow_graph"`.'
126    description: str | None
127    "New human-readable description of what this routine does."
128    event_config: dict[str, Any] | None
129    'Mapping of event types to trigger configuration. Each key is an event type string; each value is an object with a `"filters"` map and an optional `"dedupe_key_path"` (a JSON path used to deduplicate events, e.g. `"$.thread.id"`).'
130    event_type: str | None
131    "Event type that triggers this routine. Deprecated use `event_config` instead."
132    handler_type: str | None
133    'New execution model. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`.'
134    lookup_key: str | None
135    "New stable, unique key for deterministic lookup. Must be unique within the app."
136    message_policy: AgentRoutineUpdateInputMessagePolicy | None
137    "Updated visibility and explicit recipient selection for emitted messages."
138    metadata: dict[str, Any] | None
139    "Updated arbitrary key-value metadata. Replaces the existing metadata entirely."
140    name: str | None
141    "New human-readable display name for the routine."
142    preset_config: AgentRoutineUpdateInputPresetConfig | None
143    "Updated configuration passed to the preset at runtime."
144    preset_name: str | None
145    'Name of the registered preset to use. Used when `handler_type` is `"preset"`.'
146    schedule: str | None
147    'New cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour.'
148    script: str | None
149    'New inline script source. Used when `handler_type` is `"script"`.'
150    steps: list[AgentRoutineUpdateInputStepsItem] | None
151    'Updated ordered list of steps for a chain handler. Required when `handler_type` is `"chain"`; must be omitted or empty otherwise. Replaces the entire existing step list send the full desired list, not a partial diff.'
152    template: str | None
153    "AgentRoutineTemplate config ID (`cfg_...`) or lookup key. When provided, the routine's configuration is re-resolved from the template before applying other param overrides. The routine's `status`, `lookup_key`, and agent attachment are always preserved."
154    trigger_context: str | None
155    'Updated trigger context. One of `"chat_session"` or `"event"`.'
156    user: str | None
157    "Optional co-owner user ID (`usr_...`) to set on the routine. Must be supplied explicitly the caller's identity is never auto-stamped. Omit to leave the existing value unchanged; send `null` (or an empty string) to clear the current co-owner."
158
159
160class AgentRoutineInvokeInputDelivery(TypedDict, total=False):
161    message: str | None
162    "Message ID (`msg_...`) to reply to. Required when `type` is `reply`."
163    thread: str | None
164    "Destination thread ID (`thr_...`). Required when `type` is `thread`."
165    type: Required[Literal["none", "thread", "reply"]]
166    "Delivery mode. Use `none` for no delivery, `thread` to post to a conversation, or `reply` to preserve a message reply anchor."
167
168
169class AgentRoutineInvokeInput(TypedDict, total=False):
170    "Invoke a routine"
171
172    delivery: AgentRoutineInvokeInputDelivery | None
173    "Typed final-result delivery: reply to a `message`, post to a `thread`, or `none` (the default)."
174    idempotency_key: str | None
175    "Unique key used to deduplicate invocations. Resubmitting the same key returns 409 if a completed run already exists."
176    message: Required[str]
177    "The user message to send to the agent for this invocation."
178    metadata: dict[str, Any] | None
179    "Arbitrary key-value metadata attached to this invocation. Not interpreted by the platform."
180    participants: dict[str, Any] | None
181    "Map of symbolic participant refs to agent ids (`agi_...` or UUID) for distributed embed_agent handoffs. Stored in the run's top-level `participants` field."
182    session_key: str | None
183    'Arbitrary key used to identify and resume a session when `session_scope` is `"per_key"`. Required in that mode.'
184    thread_id: str | None
185    "Thread ID (`thr_...`) to post the preset output into. Omit to skip thread posting."
186    user: str | None
187    "User ID to associate with the session. For S2S and developer callers only; authenticated client callers always use their own identity."
188
189
190class AsyncAgentRoutineRunResource:
191    def __init__(self, http: HttpClient):
192        self._http = http
193
194    async def get(self, run: str) -> AgentRoutineRun:
195        """
196        Retrieve a routine run
197        Returns a single routine run by its ID. The run includes status, payload,
198        result, duration, and any structured response produced by the routine's agent.
199        The authenticated principal must have access to the app that owns the run.
200        When your API key is scoped to an app, the run must belong to that app or
201        a 403 is returned.
202
203        Args:
204            run: Routine run ID (`arr_...`) to retrieve.
205
206        Returns:
207            The requested routine run.
208        """
209        return await self._http.request(
210            f"/api/v1/agent_routines/runs/{run}",
211            response_type=AgentRoutineRun,
212        )
213
214    async def journal(
215        self, run: str, *, limit: int | None = None, after_cursor: str | None = None
216    ) -> RunJournalPage:
217        """
218        List a routine run journal
219        Returns the durable workflow journal entries for one agent routine run in
220        ascending sequence order. Script-backed, preset-backed, and legacy runs may
221        have no journal; those runs return `journal: null` and an empty `data` array
222        with HTTP 200.
223        Pagination is forward-only. Pass `after_cursor` from the previous response
224        to retrieve the next page.
225
226        Args:
227            run: Routine run ID (`arr_...`) whose journal to retrieve.
228            limit: Maximum number of entries to return. Defaults to 50; maximum is 100.
229            after_cursor: Opaque cursor from the previous response's `after_cursor` field.
230
231        Returns:
232            Forward-paginated routine run journal entries.
233        """
234        query: dict[str, object] = {}
235        if limit is not None:
236            query["limit"] = limit
237        if after_cursor is not None:
238            query["after_cursor"] = after_cursor
239        return await self._http.request(
240            f"/api/v1/agent_routines/runs/{run}/journal",
241            query=query,
242            response_type=RunJournalPage,
243        )
244
245
246class AsyncAgentRoutineResource:
247    def __init__(self, http: HttpClient):
248        self._http = http
249        self.agent_routine_runs = AsyncAgentRoutineRunResource(http)
250
251    async def list(
252        self, *, agent: builtins.list[str] | None = None, event_type: str | None = None
253    ) -> AgentRoutineListResponse:
254        """
255        List routines
256        Returns all routines within the authenticated app scope. Optionally filter by
257        agent or event type. When `agent` is omitted, all routines accessible to the
258        caller are returned regardless of which agent they belong to.
259        If `agent` is provided but does not exist or is not accessible, the endpoint
260        returns 404 rather than an empty list. Results are not paginated; all matching
261        routines are returned in a single response. Requires app scope.
262
263        Args:
264            agent: Agent IDs (`agi_...`) to filter routines by. Omit to return routines across all agents. Multiple values are OR'd.
265            event_type: Event type string to filter by (e.g. `"agentroutine.invoked"`). Omit to return routines for all event types.
266
267        Returns:
268            Object containing a `data` array of matching routines.
269        """
270        query: dict[str, object] = {}
271        if agent is not None:
272            query["agent"] = agent
273        if event_type is not None:
274            query["event_type"] = event_type
275        return await self._http.request(
276            "/api/v1/agent_routines",
277            query=query,
278            response_type=AgentRoutineListResponse,
279        )
280
281    async def presets(self) -> builtins.list[RoutinePreset]:
282        """
283        List routine presets
284        Returns all registered routine presets available to the authenticated app,
285        including each preset's name, display metadata, and accepted configuration
286        schema. Use this endpoint to discover which presets can be referenced when
287        creating or updating a routine with `handler_type: "preset"`.
288        The list reflects presets registered at server start time and does not change
289        at runtime. Requires app scope.
290
291        Returns:
292            Array of available routine preset objects.
293        """
294        return await self._http.request(
295            "/api/v1/agent_routines/presets",
296            response_type=list[RoutinePreset],
297        )
298
299    async def delete(self, routine: str) -> None:
300        """
301        Delete a routine
302        Permanently deletes the specified routine. This action is irreversible the
303        routine and its configuration are removed immediately. Any in-flight event
304        processing initiated by this routine before deletion may still complete.
305        Requires app scope. Returns 204 No Content on success.
306
307        Args:
308            routine: Routine ID (`arn_...`) of the routine to delete.
309
310        Returns:
311            Empty response on successful deletion (HTTP 204 No Content).
312        """
313        await self._http.request(f"/api/v1/agent_routines/{routine}", method="DELETE")
314
315    async def get(self, routine: str) -> AgentRoutine:
316        """
317        Retrieve a routine
318        Returns the full routine record for the given routine ID. Use this endpoint to
319        inspect a routine's current configuration, handler type, event config, schedule,
320        and lifecycle status.
321        Requires app scope. Returns 404 if the routine does not exist or is not
322        accessible to the caller.
323
324        Args:
325            routine: Routine ID (`arn_...`) of the routine to retrieve.
326
327        Returns:
328            The requested routine.
329        """
330        return await self._http.request(
331            f"/api/v1/agent_routines/{routine}",
332            response_type=AgentRoutine,
333        )
334
335    async def update(self, routine: str, input: AgentRoutineUpdateInput) -> AgentRoutine:
336        """
337        Update a routine
338        Updates one or more fields of the specified routine. Only the fields you
339        include are changed; omitted fields retain their current values. To change the
340        execution model, supply a new `handler_type` along with its required handler
341        body field (`config`, `script`, or `preset_name`).
342        When `template` is supplied, the routine's configuration is re-resolved from
343        the template before applying any additional field overrides. The routine's
344        `status`, `lookup_key`, and agent attachment are always preserved regardless
345        of template content. Updating `steps` replaces the entire step list send
346        the full desired list, not a partial diff. Requires app scope.
347
348        Args:
349            routine: Routine ID (`arn_...`) of the routine to update.
350            input: Request body.
351            input.acl: Updated access control list. Replaces the existing ACL entirely.
352            input.config: Workflow config ID (`cfg_...`). Used when `handler_type` is `"workflow_graph"`.
353            input.description: New human-readable description of what this routine does.
354            input.event_config: Mapping of event types to trigger configuration. Each key is an event type string; each value is an object with a `"filters"` map and an optional `"dedupe_key_path"` (a JSON path used to deduplicate events, e.g. `"$.thread.id"`).
355            input.event_type: Event type that triggers this routine. Deprecated use `event_config` instead.
356            input.handler_type: New execution model. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`.
357            input.lookup_key: New stable, unique key for deterministic lookup. Must be unique within the app.
358            input.message_policy: Updated visibility and explicit recipient selection for emitted messages.
359            input.metadata: Updated arbitrary key-value metadata. Replaces the existing metadata entirely.
360            input.name: New human-readable display name for the routine.
361            input.preset_config: Updated configuration passed to the preset at runtime.
362            input.preset_name: Name of the registered preset to use. Used when `handler_type` is `"preset"`.
363            input.schedule: New cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour.
364            input.script: New inline script source. Used when `handler_type` is `"script"`.
365            input.steps: Updated ordered list of steps for a chain handler. Required when `handler_type` is `"chain"`; must be omitted or empty otherwise. Replaces the entire existing step list send the full desired list, not a partial diff.
366            input.template: AgentRoutineTemplate config ID (`cfg_...`) or lookup key. When provided, the routine's configuration is re-resolved from the template before applying other param overrides. The routine's `status`, `lookup_key`, and agent attachment are always preserved.
367            input.trigger_context: Updated trigger context. One of `"chat_session"` or `"event"`.
368            input.user: Optional co-owner user ID (`usr_...`) to set on the routine. Must be supplied explicitly the caller's identity is never auto-stamped. Omit to leave the existing value unchanged; send `null` (or an empty string) to clear the current co-owner.
369
370        Returns:
371            The updated routine.
372        """
373        return await self._http.request(
374            f"/api/v1/agent_routines/{routine}",
375            method="PATCH",
376            body=input,
377            response_type=AgentRoutine,
378        )
379
380    async def activate(self, routine: str) -> AgentRoutine:
381        """
382        Activate a routine
383        Sets the routine's status to `"active"`, enabling it to process events or run
384        on its configured schedule. Only routines that have a workflow config attached
385        can be activated; attempting to activate a routine with no config returns 422.
386        Scheduled routines must be configured to run no more frequently than once per
387        hour. Activation fails with 422 if the cron schedule is more frequent than
388        that limit. Requires app scope.
389
390        Args:
391            routine: Routine ID (`arn_...`) of the routine to activate.
392
393        Returns:
394            The updated routine with `status` set to `"active"`.
395        """
396        return await self._http.request(
397            f"/api/v1/agent_routines/{routine}/activate",
398            method="POST",
399            response_type=AgentRoutine,
400        )
401
402    async def invoke(self, routine: str, input: AgentRoutineInvokeInput) -> AgentRoutineRun:
403        """
404        Invoke a routine
405        Triggers an on-demand invocation of the specified routine, dispatching an
406        asynchronous agent run and returning a run record immediately. The routine must
407        be active and must have `event_type` set to `"agentroutine.invoked"`.
408        The routine's `preset_config.session_mode` determines session behavior: each
409        call may create a new session (`"stateless"`) or reuse an existing one
410        (`"session"`). When `session_scope` is `"per_user"`, the `user` param is
411        required for S2S and developer callers; authenticated client callers always
412        use their own identity. When `session_scope` is `"per_key"`, `session_key`
413        is required.
414        Supply `idempotency_key` to safely retry invocations if a completed run
415        already exists for that key a 409 Conflict is returned rather than creating
416        a duplicate run. Entitlement for LLM calls is checked at request time;
417        customers on plans that do not include this feature receive 402.
418        Use `delivery` to propagate the final textual result into a conversation.
419        `{"type":"reply","message":"msg_..."}` preserves the message's external
420        origin (for example Slack), while `{"type":"thread","thread":"thr_..."}`
421        posts without a reply anchor. Chain routines deliver only their final result.
422        For workflow-graph routines that dispatch distributed work, pass optional
423        `participants` (map of symbolic refs to agent ids, e.g.
424        `{"investigator":"agi_..."}`) as a **top-level** field next to free-form
425        invoke inputs same shape as automation invoke. Free-form fields stay on
426        `event_payload`; participants are stored in the run's top-level
427        `participants` field and exposed through workflow system context so
428        `embed_agent` nodes can resolve assignees.
429
430        Args:
431            routine: Routine ID (`arn_...`) or `lookup_key` of the routine to invoke.
432            input: Request body.
433            input.delivery: Typed final-result delivery: reply to a `message`, post to a `thread`, or `none` (the default).
434            input.idempotency_key: Unique key used to deduplicate invocations. Resubmitting the same key returns 409 if a completed run already exists.
435            input.message: The user message to send to the agent for this invocation.
436            input.metadata: Arbitrary key-value metadata attached to this invocation. Not interpreted by the platform.
437            input.participants: Map of symbolic participant refs to agent ids (`agi_...` or UUID) for distributed embed_agent handoffs. Stored in the run's top-level `participants` field.
438            input.session_key: Arbitrary key used to identify and resume a session when `session_scope` is `"per_key"`. Required in that mode.
439            input.thread_id: Thread ID (`thr_...`) to post the preset output into. Omit to skip thread posting.
440            input.user: User ID to associate with the session. For S2S and developer callers only; authenticated client callers always use their own identity.
441
442        Returns:
443            The agent routine run created by this invocation.
444        """
445        return await self._http.request(
446            f"/api/v1/agent_routines/{routine}/invoke",
447            method="POST",
448            body=input,
449            response_type=AgentRoutineRun,
450        )
451
452    async def pause(self, routine: str) -> AgentRoutine:
453        """
454        Pause a routine
455        Sets the routine's status to `"paused"`, suspending event processing and
456        scheduled execution without deleting the routine or its configuration. A
457        paused routine can be resumed at any time by calling the activate endpoint.
458        Requires app scope.
459
460        Args:
461            routine: Routine ID (`arn_...`) of the routine to pause.
462
463        Returns:
464            The updated routine with `status` set to `"paused"`.
465        """
466        return await self._http.request(
467            f"/api/v1/agent_routines/{routine}/pause",
468            method="POST",
469            response_type=AgentRoutine,
470        )
471
472    async def runs(
473        self,
474        routine: str,
475        *,
476        status: str | None = None,
477        limit: int | None = None,
478        before_cursor: str | None = None,
479        after_cursor: str | None = None,
480    ) -> AgentRoutineRunListResponse:
481        """
482        List runs for a routine
483        Returns a cursor-paginated list of runs for the specified routine, ordered
484        from most recent to oldest by default. Use `before_cursor` and `after_cursor`
485        to page through results in either direction.
486        You can filter runs by status to monitor a specific lifecycle phase. The
487        authenticated principal must have access to the routine's parent app. When
488        your API key is scoped to an app, only runs belonging to that app are
489        returned.
490
491        Args:
492            routine: Routine ID (`rtn_...`) whose runs you want to list.
493            status: Filter runs by status. One of `"pending"`, `"running"`, `"completed"`, `"failed"`, or `"skipped"`. Omit to return runs in all statuses.
494            limit: Maximum number of runs to return per page. Defaults to 50; maximum is 100.
495            before_cursor: Opaque cursor from a previous response's `before_cursor` field. Returns the page of runs older than this cursor.
496            after_cursor: Opaque cursor from a previous response's `after_cursor` field. Returns the page of runs newer than this cursor.
497
498        Returns:
499            Paginated list of routine runs.
500        """
501        query: dict[str, object] = {}
502        if status is not None:
503            query["status"] = status
504        if limit is not None:
505            query["limit"] = limit
506        if before_cursor is not None:
507            query["before_cursor"] = before_cursor
508        if after_cursor is not None:
509            query["after_cursor"] = after_cursor
510        return await self._http.request(
511            f"/api/v1/agent_routines/{routine}/runs",
512            query=query,
513            response_type=AgentRoutineRunListResponse,
514        )
515
516
517class AgentRoutineRunResource:
518    def __init__(self, http: SyncHttpClient):
519        self._http = http
520
521    def get(self, run: str) -> AgentRoutineRun:
522        """
523        Retrieve a routine run
524        Returns a single routine run by its ID. The run includes status, payload,
525        result, duration, and any structured response produced by the routine's agent.
526        The authenticated principal must have access to the app that owns the run.
527        When your API key is scoped to an app, the run must belong to that app or
528        a 403 is returned.
529
530        Args:
531            run: Routine run ID (`arr_...`) to retrieve.
532
533        Returns:
534            The requested routine run.
535        """
536        return self._http.request(
537            f"/api/v1/agent_routines/runs/{run}",
538            response_type=AgentRoutineRun,
539        )
540
541    def journal(
542        self, run: str, *, limit: int | None = None, after_cursor: str | None = None
543    ) -> RunJournalPage:
544        """
545        List a routine run journal
546        Returns the durable workflow journal entries for one agent routine run in
547        ascending sequence order. Script-backed, preset-backed, and legacy runs may
548        have no journal; those runs return `journal: null` and an empty `data` array
549        with HTTP 200.
550        Pagination is forward-only. Pass `after_cursor` from the previous response
551        to retrieve the next page.
552
553        Args:
554            run: Routine run ID (`arr_...`) whose journal to retrieve.
555            limit: Maximum number of entries to return. Defaults to 50; maximum is 100.
556            after_cursor: Opaque cursor from the previous response's `after_cursor` field.
557
558        Returns:
559            Forward-paginated routine run journal entries.
560        """
561        query: dict[str, object] = {}
562        if limit is not None:
563            query["limit"] = limit
564        if after_cursor is not None:
565            query["after_cursor"] = after_cursor
566        return self._http.request(
567            f"/api/v1/agent_routines/runs/{run}/journal",
568            query=query,
569            response_type=RunJournalPage,
570        )
571
572
573class AgentRoutineResource:
574    def __init__(self, http: SyncHttpClient):
575        self._http = http
576        self.agent_routine_runs = AgentRoutineRunResource(http)
577
578    def list(
579        self, *, agent: builtins.list[str] | None = None, event_type: str | None = None
580    ) -> AgentRoutineListResponse:
581        """
582        List routines
583        Returns all routines within the authenticated app scope. Optionally filter by
584        agent or event type. When `agent` is omitted, all routines accessible to the
585        caller are returned regardless of which agent they belong to.
586        If `agent` is provided but does not exist or is not accessible, the endpoint
587        returns 404 rather than an empty list. Results are not paginated; all matching
588        routines are returned in a single response. Requires app scope.
589
590        Args:
591            agent: Agent IDs (`agi_...`) to filter routines by. Omit to return routines across all agents. Multiple values are OR'd.
592            event_type: Event type string to filter by (e.g. `"agentroutine.invoked"`). Omit to return routines for all event types.
593
594        Returns:
595            Object containing a `data` array of matching routines.
596        """
597        query: dict[str, object] = {}
598        if agent is not None:
599            query["agent"] = agent
600        if event_type is not None:
601            query["event_type"] = event_type
602        return self._http.request(
603            "/api/v1/agent_routines",
604            query=query,
605            response_type=AgentRoutineListResponse,
606        )
607
608    def presets(self) -> builtins.list[RoutinePreset]:
609        """
610        List routine presets
611        Returns all registered routine presets available to the authenticated app,
612        including each preset's name, display metadata, and accepted configuration
613        schema. Use this endpoint to discover which presets can be referenced when
614        creating or updating a routine with `handler_type: "preset"`.
615        The list reflects presets registered at server start time and does not change
616        at runtime. Requires app scope.
617
618        Returns:
619            Array of available routine preset objects.
620        """
621        return self._http.request(
622            "/api/v1/agent_routines/presets",
623            response_type=list[RoutinePreset],
624        )
625
626    def delete(self, routine: str) -> None:
627        """
628        Delete a routine
629        Permanently deletes the specified routine. This action is irreversible the
630        routine and its configuration are removed immediately. Any in-flight event
631        processing initiated by this routine before deletion may still complete.
632        Requires app scope. Returns 204 No Content on success.
633
634        Args:
635            routine: Routine ID (`arn_...`) of the routine to delete.
636
637        Returns:
638            Empty response on successful deletion (HTTP 204 No Content).
639        """
640        self._http.request(f"/api/v1/agent_routines/{routine}", method="DELETE")
641
642    def get(self, routine: str) -> AgentRoutine:
643        """
644        Retrieve a routine
645        Returns the full routine record for the given routine ID. Use this endpoint to
646        inspect a routine's current configuration, handler type, event config, schedule,
647        and lifecycle status.
648        Requires app scope. Returns 404 if the routine does not exist or is not
649        accessible to the caller.
650
651        Args:
652            routine: Routine ID (`arn_...`) of the routine to retrieve.
653
654        Returns:
655            The requested routine.
656        """
657        return self._http.request(f"/api/v1/agent_routines/{routine}", response_type=AgentRoutine)
658
659    def update(self, routine: str, input: AgentRoutineUpdateInput) -> AgentRoutine:
660        """
661        Update a routine
662        Updates one or more fields of the specified routine. Only the fields you
663        include are changed; omitted fields retain their current values. To change the
664        execution model, supply a new `handler_type` along with its required handler
665        body field (`config`, `script`, or `preset_name`).
666        When `template` is supplied, the routine's configuration is re-resolved from
667        the template before applying any additional field overrides. The routine's
668        `status`, `lookup_key`, and agent attachment are always preserved regardless
669        of template content. Updating `steps` replaces the entire step list send
670        the full desired list, not a partial diff. Requires app scope.
671
672        Args:
673            routine: Routine ID (`arn_...`) of the routine to update.
674            input: Request body.
675            input.acl: Updated access control list. Replaces the existing ACL entirely.
676            input.config: Workflow config ID (`cfg_...`). Used when `handler_type` is `"workflow_graph"`.
677            input.description: New human-readable description of what this routine does.
678            input.event_config: Mapping of event types to trigger configuration. Each key is an event type string; each value is an object with a `"filters"` map and an optional `"dedupe_key_path"` (a JSON path used to deduplicate events, e.g. `"$.thread.id"`).
679            input.event_type: Event type that triggers this routine. Deprecated use `event_config` instead.
680            input.handler_type: New execution model. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`.
681            input.lookup_key: New stable, unique key for deterministic lookup. Must be unique within the app.
682            input.message_policy: Updated visibility and explicit recipient selection for emitted messages.
683            input.metadata: Updated arbitrary key-value metadata. Replaces the existing metadata entirely.
684            input.name: New human-readable display name for the routine.
685            input.preset_config: Updated configuration passed to the preset at runtime.
686            input.preset_name: Name of the registered preset to use. Used when `handler_type` is `"preset"`.
687            input.schedule: New cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour.
688            input.script: New inline script source. Used when `handler_type` is `"script"`.
689            input.steps: Updated ordered list of steps for a chain handler. Required when `handler_type` is `"chain"`; must be omitted or empty otherwise. Replaces the entire existing step list send the full desired list, not a partial diff.
690            input.template: AgentRoutineTemplate config ID (`cfg_...`) or lookup key. When provided, the routine's configuration is re-resolved from the template before applying other param overrides. The routine's `status`, `lookup_key`, and agent attachment are always preserved.
691            input.trigger_context: Updated trigger context. One of `"chat_session"` or `"event"`.
692            input.user: Optional co-owner user ID (`usr_...`) to set on the routine. Must be supplied explicitly the caller's identity is never auto-stamped. Omit to leave the existing value unchanged; send `null` (or an empty string) to clear the current co-owner.
693
694        Returns:
695            The updated routine.
696        """
697        return self._http.request(
698            f"/api/v1/agent_routines/{routine}",
699            method="PATCH",
700            body=input,
701            response_type=AgentRoutine,
702        )
703
704    def activate(self, routine: str) -> AgentRoutine:
705        """
706        Activate a routine
707        Sets the routine's status to `"active"`, enabling it to process events or run
708        on its configured schedule. Only routines that have a workflow config attached
709        can be activated; attempting to activate a routine with no config returns 422.
710        Scheduled routines must be configured to run no more frequently than once per
711        hour. Activation fails with 422 if the cron schedule is more frequent than
712        that limit. Requires app scope.
713
714        Args:
715            routine: Routine ID (`arn_...`) of the routine to activate.
716
717        Returns:
718            The updated routine with `status` set to `"active"`.
719        """
720        return self._http.request(
721            f"/api/v1/agent_routines/{routine}/activate",
722            method="POST",
723            response_type=AgentRoutine,
724        )
725
726    def invoke(self, routine: str, input: AgentRoutineInvokeInput) -> AgentRoutineRun:
727        """
728        Invoke a routine
729        Triggers an on-demand invocation of the specified routine, dispatching an
730        asynchronous agent run and returning a run record immediately. The routine must
731        be active and must have `event_type` set to `"agentroutine.invoked"`.
732        The routine's `preset_config.session_mode` determines session behavior: each
733        call may create a new session (`"stateless"`) or reuse an existing one
734        (`"session"`). When `session_scope` is `"per_user"`, the `user` param is
735        required for S2S and developer callers; authenticated client callers always
736        use their own identity. When `session_scope` is `"per_key"`, `session_key`
737        is required.
738        Supply `idempotency_key` to safely retry invocations if a completed run
739        already exists for that key a 409 Conflict is returned rather than creating
740        a duplicate run. Entitlement for LLM calls is checked at request time;
741        customers on plans that do not include this feature receive 402.
742        Use `delivery` to propagate the final textual result into a conversation.
743        `{"type":"reply","message":"msg_..."}` preserves the message's external
744        origin (for example Slack), while `{"type":"thread","thread":"thr_..."}`
745        posts without a reply anchor. Chain routines deliver only their final result.
746        For workflow-graph routines that dispatch distributed work, pass optional
747        `participants` (map of symbolic refs to agent ids, e.g.
748        `{"investigator":"agi_..."}`) as a **top-level** field next to free-form
749        invoke inputs same shape as automation invoke. Free-form fields stay on
750        `event_payload`; participants are stored in the run's top-level
751        `participants` field and exposed through workflow system context so
752        `embed_agent` nodes can resolve assignees.
753
754        Args:
755            routine: Routine ID (`arn_...`) or `lookup_key` of the routine to invoke.
756            input: Request body.
757            input.delivery: Typed final-result delivery: reply to a `message`, post to a `thread`, or `none` (the default).
758            input.idempotency_key: Unique key used to deduplicate invocations. Resubmitting the same key returns 409 if a completed run already exists.
759            input.message: The user message to send to the agent for this invocation.
760            input.metadata: Arbitrary key-value metadata attached to this invocation. Not interpreted by the platform.
761            input.participants: Map of symbolic participant refs to agent ids (`agi_...` or UUID) for distributed embed_agent handoffs. Stored in the run's top-level `participants` field.
762            input.session_key: Arbitrary key used to identify and resume a session when `session_scope` is `"per_key"`. Required in that mode.
763            input.thread_id: Thread ID (`thr_...`) to post the preset output into. Omit to skip thread posting.
764            input.user: User ID to associate with the session. For S2S and developer callers only; authenticated client callers always use their own identity.
765
766        Returns:
767            The agent routine run created by this invocation.
768        """
769        return self._http.request(
770            f"/api/v1/agent_routines/{routine}/invoke",
771            method="POST",
772            body=input,
773            response_type=AgentRoutineRun,
774        )
775
776    def pause(self, routine: str) -> AgentRoutine:
777        """
778        Pause a routine
779        Sets the routine's status to `"paused"`, suspending event processing and
780        scheduled execution without deleting the routine or its configuration. A
781        paused routine can be resumed at any time by calling the activate endpoint.
782        Requires app scope.
783
784        Args:
785            routine: Routine ID (`arn_...`) of the routine to pause.
786
787        Returns:
788            The updated routine with `status` set to `"paused"`.
789        """
790        return self._http.request(
791            f"/api/v1/agent_routines/{routine}/pause",
792            method="POST",
793            response_type=AgentRoutine,
794        )
795
796    def runs(
797        self,
798        routine: str,
799        *,
800        status: str | None = None,
801        limit: int | None = None,
802        before_cursor: str | None = None,
803        after_cursor: str | None = None,
804    ) -> AgentRoutineRunListResponse:
805        """
806        List runs for a routine
807        Returns a cursor-paginated list of runs for the specified routine, ordered
808        from most recent to oldest by default. Use `before_cursor` and `after_cursor`
809        to page through results in either direction.
810        You can filter runs by status to monitor a specific lifecycle phase. The
811        authenticated principal must have access to the routine's parent app. When
812        your API key is scoped to an app, only runs belonging to that app are
813        returned.
814
815        Args:
816            routine: Routine ID (`rtn_...`) whose runs you want to list.
817            status: Filter runs by status. One of `"pending"`, `"running"`, `"completed"`, `"failed"`, or `"skipped"`. Omit to return runs in all statuses.
818            limit: Maximum number of runs to return per page. Defaults to 50; maximum is 100.
819            before_cursor: Opaque cursor from a previous response's `before_cursor` field. Returns the page of runs older than this cursor.
820            after_cursor: Opaque cursor from a previous response's `after_cursor` field. Returns the page of runs newer than this cursor.
821
822        Returns:
823            Paginated list of routine runs.
824        """
825        query: dict[str, object] = {}
826        if status is not None:
827            query["status"] = status
828        if limit is not None:
829            query["limit"] = limit
830        if before_cursor is not None:
831            query["before_cursor"] = before_cursor
832        if after_cursor is not None:
833            query["after_cursor"] = after_cursor
834        return self._http.request(
835            f"/api/v1/agent_routines/{routine}/runs",
836            query=query,
837            response_type=AgentRoutineRunListResponse,
838        )