Class AgentRoutineResource

constructor

• new AgentRoutineResource(http: HttpClient): AgentRoutineResource

  Parameters

  • http: HttpClient

  Returns AgentRoutineResource

Readonlyagent_routine_runs

activate

• activate(routine: string): Promise<AgentRoutine>

  Activate a routine Sets the routine's status to "active", enabling it to process events or run on its configured schedule. Only routines that have a workflow config attached can be activated; attempting to activate a routine with no config returns 422. Scheduled routines must be configured to run no more frequently than once per hour. Activation fails with 422 if the cron schedule is more frequent than that limit. Requires app scope.

  Parameters

  • routine: string

    Routine ID (arn_...) of the routine to activate.

  Returns Promise<AgentRoutine>

  The updated routine with status set to "active".

delete

• delete(routine: string): Promise<void>

  Delete a routine Permanently deletes the specified routine. This action is irreversible — the routine and its configuration are removed immediately. Any in-flight event processing initiated by this routine before deletion may still complete. Requires app scope. Returns 204 No Content on success.

  Parameters

  • routine: string

    Routine ID (arn_...) of the routine to delete.

  Returns Promise<void>

  Empty response on successful deletion (HTTP 204 No Content).

get

• get(routine: string): Promise<AgentRoutine>

  Retrieve a routine Returns the full routine record for the given routine ID. Use this endpoint to inspect a routine's current configuration, handler type, event config, schedule, and lifecycle status. Requires app scope. Returns 404 if the routine does not exist or is not accessible to the caller.

  Parameters

  • routine: string

    Routine ID (arn_...) of the routine to retrieve.

  Returns Promise<AgentRoutine>

  The requested routine.

invoke

• invoke(
      routine: string,
      input: {
          idempotency_key?: string;
          message: string;
          metadata?: Record<string, unknown>;
          session_key?: string;
          thread_id?: string;
          user?: string;
      },
  ): Promise<AgentRoutineRun>

  Invoke a routine Triggers an on-demand invocation of the specified routine, dispatching an asynchronous agent run and returning a run record immediately. The routine must be active and must have event_type set to "agentroutine.invoked". The routine's preset_config.session_mode determines session behavior: each call may create a new session ("stateless") or reuse an existing one ("session"). When session_scope is "per_user", the user param is required for S2S and developer callers; authenticated client callers always use their own identity. When session_scope is "per_key", session_key is required. Supply idempotency_key to safely retry invocations — if a completed run already exists for that key a 409 Conflict is returned rather than creating a duplicate run. Entitlement for LLM calls is checked at request time; customers on plans that do not include this feature receive 402.

  Parameters

  • routine: string

    Routine ID (arn_...) or lookup_key of the routine to invoke.

  • input: {
        idempotency_key?: string;
        message: string;
        metadata?: Record<string, unknown>;
        session_key?: string;
        thread_id?: string;
        user?: string;
    }

    Request body.

    • Optionalidempotency_key?: string

      Unique key used to deduplicate invocations. Resubmitting the same key returns 409 if a completed run already exists.

    • message: string

      The user message to send to the agent for this invocation.

    • Optionalmetadata?: Record<string, unknown>

      Arbitrary key-value metadata attached to this invocation. Not interpreted by the platform.

    • Optionalsession_key?: string

      Arbitrary key used to identify and resume a session when session_scope is "per_key". Required in that mode.

    • Optionalthread_id?: string

      Thread ID (thr_...) to post the preset output into. Omit to skip thread posting.

    • Optionaluser?: string

      User ID to associate with the session. For S2S and developer callers only; authenticated client callers always use their own identity.

  Returns Promise<AgentRoutineRun>

  The agent routine run created by this invocation.

list

• list(
      params?: { agent?: string; eventType?: string },
  ): Promise<AgentRoutineListResponse>

  List routines Returns all routines within the authenticated app scope. Optionally filter by agent or event type. When agent is omitted, all routines accessible to the caller are returned regardless of which agent they belong to. If agent is provided but does not exist or is not accessible, the endpoint returns 404 rather than an empty list. Results are not paginated; all matching routines are returned in a single response. Requires app scope.

  Parameters

  • Optionalparams: { agent?: string; eventType?: string }

    Query parameters.

    • Optionalagent?: string

      Agent ID (agt_...) to filter routines by. Omit to return routines across all agents.

    • OptionaleventType?: string

      Event type string to filter by (e.g. "agentroutine.invoked"). Omit to return routines for all event types.

  Returns Promise<AgentRoutineListResponse>

  Object containing a data array of matching routines.

pause

• pause(routine: string): Promise<AgentRoutine>

  Pause a routine Sets the routine's status to "paused", suspending event processing and scheduled execution without deleting the routine or its configuration. A paused routine can be resumed at any time by calling the activate endpoint. Requires app scope.

  Parameters

  • routine: string

    Routine ID (arn_...) of the routine to pause.

  Returns Promise<AgentRoutine>

  The updated routine with status set to "paused".

presets

• presets(): Promise<RoutinePreset[]>

  List routine presets Returns all registered routine presets available to the authenticated app, including each preset's name, display metadata, and accepted configuration schema. Use this endpoint to discover which presets can be referenced when creating or updating a routine with handler_type: "preset". The list reflects presets registered at server start time and does not change at runtime. Requires app scope.

  Returns Promise<RoutinePreset[]>

  Array of available routine preset objects.

runs

• runs(
      routine: string,
      params?: {
          afterCursor?: string;
          beforeCursor?: string;
          limit?: number;
          status?: string;
      },
  ): Promise<AgentRoutineRunListResponse>

  List runs for a routine Returns a cursor-paginated list of runs for the specified routine, ordered from most recent to oldest by default. Use before_cursor and after_cursor to page through results in either direction. You can filter runs by status to monitor a specific lifecycle phase. The authenticated principal must have access to the routine's parent app. When your API key is scoped to an app, only runs belonging to that app are returned.

  Parameters

  • routine: string

    Routine ID (rtn_...) whose runs you want to list.

  • Optionalparams: { afterCursor?: string; beforeCursor?: string; limit?: number; status?: string }

    Query parameters.

    • OptionalafterCursor?: string

      Opaque cursor from a previous response's after_cursor field. Returns the page of runs newer than this cursor.

    • OptionalbeforeCursor?: string

      Opaque cursor from a previous response's before_cursor field. Returns the page of runs older than this cursor.

    • Optionallimit?: number

      Maximum number of runs to return per page. Defaults to 50; maximum is 100.

    • Optionalstatus?: string

      Filter runs by status. One of "pending", "running", "completed", "failed", or "skipped". Omit to return runs in all statuses.

  Returns Promise<AgentRoutineRunListResponse>

  Paginated list of routine runs.

update

• update(
      routine: string,
      input: {
          acl?: {
              add?: {
                  actions: string[];
                  principal?: string;
                  principal_type: string;
              }[];
              grants?: {
                  actions: string[];
                  principal?: string;
                  principal_type: string;
              }[];
              remove?: { principal?: string; principal_type: string }[];
          };
          config?: string;
          description?: string;
          event_config?: Record<string, unknown>;
          event_type?: string;
          handler_type?: string;
          lookup_key?: string;
          metadata?: Record<string, unknown>;
          name?: string;
          preset_config?: {
              instructions?: string;
              llm?: { model?: string };
              session_mode?: string;
              session_scope?: string;
              structured_message_template_ids?: string[];
          };
          preset_name?: string;
          schedule?: string;
          script?: string;
          steps?: {
              config?: string;
              handler_type: string;
              inputs?: Record<string, unknown>;
              name?: string;
              on_error?: string;
              output_key?: string;
              preset_config?: {
                  instructions?: string;
                  llm?: { model?: string };
                  session_mode?: string;
                  session_scope?: string;
                  structured_message_template_ids?: string[];
              };
              preset_name?: string;
              script?: string;
          }[];
          template?: string;
          trigger_context?: string;
      },
  ): Promise<AgentRoutine>

  Update a routine Updates one or more fields of the specified routine. Only the fields you include are changed; omitted fields retain their current values. To change the execution model, supply a new handler_type along with its required handler body field (config, script, or preset_name). When template is supplied, the routine's configuration is re-resolved from the template before applying any additional field overrides. The routine's status, lookup_key, and agent attachment are always preserved regardless of template content. Updating steps replaces the entire step list — send the full desired list, not a partial diff. Requires app scope.

  Parameters

  • routine: string

    Routine ID (arn_...) of the routine to update.

  • input: {
        acl?: {
            add?: { actions: string[]; principal?: string; principal_type: string }[];
            grants?: { actions: string[]; principal?: string; principal_type: string }[];
            remove?: { principal?: string; principal_type: string }[];
        };
        config?: string;
        description?: string;
        event_config?: Record<string, unknown>;
        event_type?: string;
        handler_type?: string;
        lookup_key?: string;
        metadata?: Record<string, unknown>;
        name?: string;
        preset_config?: {
            instructions?: string;
            llm?: { model?: string };
            session_mode?: string;
            session_scope?: string;
            structured_message_template_ids?: string[];
        };
        preset_name?: string;
        schedule?: string;
        script?: string;
        steps?: {
            config?: string;
            handler_type: string;
            inputs?: Record<string, unknown>;
            name?: string;
            on_error?: string;
            output_key?: string;
            preset_config?: {
                instructions?: string;
                llm?: { model?: string };
                session_mode?: string;
                session_scope?: string;
                structured_message_template_ids?: string[];
            };
            preset_name?: string;
            script?: string;
        }[];
        template?: string;
        trigger_context?: string;
    }

    Request body.

    • Optionalacl?: {
          add?: { actions: string[]; principal?: string; principal_type: string }[];
          grants?: { actions: string[]; principal?: string; principal_type: string }[];
          remove?: { principal?: string; principal_type: string }[];
      }

      Updated access control list. Replaces the existing ACL entirely.

    • Optionalconfig?: string

      Workflow config ID (cfg_...). Used when handler_type is "workflow_graph".

    • Optionaldescription?: string

      New human-readable description of what this routine does.

    • Optionalevent_config?: Record<string, unknown>

      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").

    • Optionalevent_type?: string

      Event type that triggers this routine. Deprecated — use event_config instead.

    • Optionalhandler_type?: string

      New execution model. One of "workflow_graph", "script", "preset", or "chain".

    • Optionallookup_key?: string

      New stable, unique key for deterministic lookup. Must be unique within the app.

    • Optionalmetadata?: Record<string, unknown>

      Updated arbitrary key-value metadata. Replaces the existing metadata entirely.

    • Optionalname?: string

      New human-readable display name for the routine.

    • Optionalpreset_config?: {
          instructions?: string;
          llm?: { model?: string };
          session_mode?: string;
          session_scope?: string;
          structured_message_template_ids?: string[];
      }

      Updated configuration passed to the preset at runtime.

    • Optionalpreset_name?: string

      Name of the registered preset to use. Used when handler_type is "preset".

    • Optionalschedule?: string

      New cron expression for time-triggered routines (e.g. "0 9 * * 1"). Must not be more frequent than once per hour.

    • Optionalscript?: string

      New inline script source. Used when handler_type is "script".

    • Optionalsteps?: {
          config?: string;
          handler_type: string;
          inputs?: Record<string, unknown>;
          name?: string;
          on_error?: string;
          output_key?: string;
          preset_config?: {
              instructions?: string;
              llm?: { model?: string };
              session_mode?: string;
              session_scope?: string;
              structured_message_template_ids?: string[];
          };
          preset_name?: string;
          script?: string;
      }[]

      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.

    • Optionaltemplate?: string

      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.

    • Optionaltrigger_context?: string

      Updated trigger context. One of "chat_session" or "event".

  Returns Promise<AgentRoutine>

  The updated routine.