archastro.platform.v1.resources.agent_routines

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