v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Create a routine

Creates a new routine and attaches it to the specified agent. Routines define how an agent responds to events or a cron schedule; the handler_type controls which execution model is used.

The routine is created in "draft" status by default. To start processing events immediately, either pass status: "active" or call the activate endpoint after creation. Scheduled routines must run no more frequently than once per hour. Requires app scope.

post/api/v1/agents/{agent}/agent_routines

Path parameters

agentstring required

Agent ID (agt_...) that this routine will be attached to.

Request body

configstring

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

descriptionstring

Optional human-readable description of what this routine does.

event_configobject

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

event_typestring

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

handler_typestring required

Execution model for this routine. One of "workflow_graph", "script", "preset", or "chain".

lookup_keystring

Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app.

metadataobject

Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform.

namestring required

Human-readable display name for the routine.

preset_namestring

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

schedulestring

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

scriptstring

Inline script source. Required when handler_type is "script".

statusstring

Initial lifecycle status. One of "draft" or "active". Defaults to "draft".

trigger_contextstring

Context in which the routine is triggered. One of "chat_session" or "event". Defaults to "event".

Example request

{
  "acl": {
    "add": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "grants": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "remove": [
      {
        "principal": "string",
        "principal_type": "user"
      }
    ]
  },
  "config": "string",
  "description": "An example description.",
  "event_config": {},
  "event_type": "string",
  "handler_type": "string",
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "preset_config": {
    "instructions": "You are a helpful assistant. Answer questions concisely and cite sources when possible.",
    "llm": {
      "model": "claude-sonnet-4-5"
    },
    "session_mode": "stateless",
    "session_scope": "per_user",
    "structured_message_template_ids": [
      "string"
    ]
  },
  "preset_name": "Example Name",
  "schedule": "string",
  "script": "string",
  "status": "string",
  "steps": [
    {
      "config": "string",
      "handler_type": "preset",
      "inputs": {},
      "name": "Example Name",
      "on_error": "halt",
      "output_key": "string",
      "preset_config": {
        "instructions": "You are a helpful assistant. Answer questions concisely and cite sources when possible.",
        "llm": {
          "model": "claude-sonnet-4-5"
        },
        "session_mode": "stateless",
        "session_scope": "per_user",
        "structured_message_template_ids": [
          "string"
        ]
      },
      "preset_name": "Example Name",
      "script": "string"
    }
  ],
  "trigger_context": "string"
}

Response

Successful response

agentstring

ID of the agent that owns this routine (agi_...).

appstring

Application that scopes this routine (dap_...).

configstring

ID of the Config record that backs this routine's configuration (cfg_...). null when the routine is not config-backed.

created_atstring date-time

When this routine was created (ISO 8601).

descriptionstring

Optional description of what this routine does. null when not set.

event_configobject

Additional configuration controlling how the event trigger is matched or filtered. Shape depends on event_type. null when not configured.

event_typestring

Platform event type that triggers this routine, e.g. "agentroutine.invoked". null for schedule-only routines.

handler_typestring

Execution strategy for this routine. One of "workflow_graph", "script", "preset", or "chain".

idstring required

Routine ID (arn_...).

last_applied_template_configstring

ID of the AgentRoutineTemplate Config this routine was last provisioned or updated from (cfg_...). null for hand-built routines.

lookup_keystring

Unique human-readable key used to look up this routine without knowing its ID. null when not set.

metadataobject

Arbitrary key-value metadata attached to this routine. null when not set.

namestring

Human-readable name for the routine.

preset_namestring

Name of the preset invoked when handler_type is "preset". null for other handler types.

schedulestring

Cron expression controlling when the routine fires on a schedule. null for event-only routines.

scriptstring

Inline script body executed when handler_type is "script". null for other handler types.

statusstring

Lifecycle status of the routine. One of "draft", "active", or "paused". Only "active" routines respond to triggers.

stepsobject[]

Ordered list of chain steps (present when handler_type is "chain"). Each step is a plain map with handler_type, optional body fields (preset_name / preset_config / script / config), and step-local plumbing (name, inputs, output_key, on_error).

trigger_contextstring

Execution context in which runs are created. One of "event" (background job) or "chat_session" (interactive session). Defaults to "event".

updated_atstring date-time

When this routine was last updated (ISO 8601).

Example response

{
  "acl": {
    "add": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "grants": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "remove": [
      {
        "principal": "string",
        "principal_type": "user"
      }
    ]
  },
  "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
  "config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "description": "An example description.",
  "event_config": {},
  "event_type": "agentroutine.invoked",
  "handler_type": "script",
  "id": "arn_0aBcDeFgHiJkLmNoPqRsTu",
  "last_applied_template_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
  "lookup_key": "daily-digest",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "preset_config": {
    "instructions": "You are a helpful assistant. Answer questions concisely and cite sources when possible.",
    "llm": {
      "model": "claude-sonnet-4-5"
    },
    "session_mode": "stateless",
    "session_scope": "per_user",
    "structured_message_template_ids": [
      "string"
    ]
  },
  "preset_name": "Example Name",
  "schedule": "string",
  "script": "string",
  "status": "active",
  "steps": [
    {}
  ],
  "trigger_context": "event",
  "updated_at": "2024-01-01T00:00:00Z"
}