Features

Process Definitions

State machines that guide your agent through structured checkpoints before it can proceed. Stop agentic drift before it starts.

State machine — deploy-gate

env-check

migration-check

traffic-check

✓ complete

agent › Is the target environment correct?

What are Process Definitions?

A Process Definition is a state machine that guides an agent through a structured workflow. Instead of letting the agent run freely, you define a sequence of checkpoints — states — where the agent must answer a question before proceeding.

Each state poses a question to the agent. The agent picks one of the configured answers, which determines the next state (or terminates the session). Answers can also trigger actions like blocking the session, completing it early, or notifying you for human review.

Common uses: daily standups, deployment checklists, budget approval gates, escalation paths, code review confirmations.

Data Structure Reference

A complete process definition as stored in the API:

{
  "id":             "proc_01abc…",          // system-assigned UUID
  "name":           "deploy-gate",           // lowercase alphanumeric + hyphens
  "initial":        "env-check",             // first state the agent enters
  "initial_prompt": "Walk through the deployment checklist…",
  "states": {
    "env-check": {
      "question": "Is the target environment correct?",
      "answers": {
        "yes": { "next": "migration-check" },
        "no":  { "next": null, "action": "block" }
      }
    },
    "migration-check": {
      "question": "Have all migrations been reviewed?",
      "answers": {
        "yes": { "next": null, "action": "complete" },
        "n/a": { "next": null, "action": "complete" },
        "no":  { "next": null, "action": "block" }
      }
    }
  },
  "policy": { … },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

State Machine Concepts

Process fields

Field	Type	Description
`name`	string	Process identifier. Lowercase alphanumeric + hyphens (e.g. deploy-gate). Immutable after creation.
`initial`	string	Key of the state the agent enters when a session starts.
`initial_prompt`	string?	Optional text injected before the first agent turn. Useful for framing the task.
`states`	Record<string, State>	Map of state key → state definition. Keys must match answer.next values.
`session_budget_usd`	number?	Hard cap on session cost. The hooks enforcer denies tool calls once the running session cost reaches this number.
`email_config`	EmailConfig?	Per-session email limits: max_emails_per_session, allowed_from, allowed_to. Enforced by the outbound proxy for the resend-email tool.
`allowed_tools`	string[]?	MCP tools this process may invoke via `/mcp/process`. Intersected with the endpoint's routine-safe whitelist (memory/task/process_step) — names outside the whitelist are silently ignored. Omit to use the full whitelist. See Routines → MCP for routines.

State fields

Field	Type	Description
`question`	string	The question posed to the agent at this checkpoint.
`answers`	Record<string, Answer>	Map of answer key → answer definition. A state with no answers is terminal.

Answer fields

Field	Type	Description
`next`	string \| null	Key of the next state. null means this answer terminates the session.
`action`	"block" \| "warn" \| "complete" \| "notify_human"?	Optional side effect when this answer is chosen.

Answer actions

Action	Effect
`block`	Terminates the session and marks it as blocked. The agent cannot continue.
`warn`	Continues the session but emits a warning in the log.
`complete`	Marks the session as successfully completed.
`notify_human`	Pauses the session and notifies you for manual review before the agent continues.

Policy Configuration

A Policy attaches RBAC to a process. Every tool call the agent makes during a session is evaluated against policy rules before execution.

{
  "role": "agent",
  "allow": [
    {
      "capability": "bash",
      "rate_limit": { "max_calls": 100, "window_seconds": 3600 }
    }
  ],
  "ask": [
    {
      "capability": "mcp:filesystem:write_file",
      "budget_limit": { "max_usd": 5.00, "period": "daily" }
    }
  ],
  "deny": [
    { "capability": "mcp:filesystem:delete_file" }
  ]
}

Policy fields

Field	Type	Description
`role`	string	Identifies the agent role. Typically "agent".
`allow`	PolicyRule[]?	Capabilities the agent may call without interruption.
`ask`	PolicyRule[]?	Capabilities that trigger a human-approval pause.
`deny`	Array<{capability}>?	Capabilities the agent is never allowed to call.

PolicyRule fields

Field	Type	Description
`capability`	string	The capability to match (see Capability Patterns).
`rate_limit`	{max_calls, window_seconds}?	Max calls in a rolling time window.
`budget_limit`	{max_usd, period}?	Max USD per period. period is "hourly", "daily", or "monthly".

Capability Patterns

Capability strings follow a hierarchical dot/colon path. Wildcards (*) match any suffix.

Pattern	Matches
`bash`	Any bash/shell execution.
`mcp:*`	All MCP tool calls across all servers.
`mcp:filesystem:*`	All tools on the filesystem MCP server.
`mcp:filesystem:write_file`	Exactly the write_file tool on the filesystem MCP server.
`mcp:resend:*`	All tools on the resend MCP server.

Rule evaluation order: deny first, then ask, then allow. If no rule matches, the call is allowed by default.

Rate & Budget Limits

Both allow and ask rules support optional rate and budget limits. When a limit is exceeded, the capability is treated as denied for that window or period.

Field	Description
`rate_limit.max_calls`	Maximum number of calls allowed within window_seconds.
`rate_limit.window_seconds`	Rolling window in seconds (e.g. 3600 = 1 hour).
`budget_limit.max_usd`	Maximum USD spend per period. Applies to tools that report a cost.
`budget_limit.period`	"hourly", "daily", or "monthly". Resets at the start of each period.

Full Example: Deploy Gate with Policy

A three-step deployment checklist that blocks on any failure, combined with a policy that allows bash but asks before any MCP filesystem writes:

{
  "name": "deploy-gate",
  "initial": "env-check",
  "initial_prompt": "Walk through the deployment checklist before pushing to production.",
  "states": {
    "env-check": {
      "question": "Is the target environment correct (not accidentally staging → prod)?",
      "answers": {
        "yes": { "next": "migration-check" },
        "no":  { "next": null, "action": "block" }
      }
    },
    "migration-check": {
      "question": "Have all database migrations been reviewed and tested?",
      "answers": {
        "yes": { "next": "traffic-check" },
        "n/a": { "next": "traffic-check" },
        "no":  { "next": null, "action": "block" }
      }
    },
    "traffic-check": {
      "question": "Is it safe to shift traffic now (no peak hours, no active incidents)?",
      "answers": {
        "yes": { "next": null, "action": "complete" },
        "no":  { "next": null, "action": "block" }
      }
    }
  },
  "policy": {
    "role": "agent",
    "allow": [
      { "capability": "bash", "rate_limit": { "max_calls": 50, "window_seconds": 3600 } }
    ],
    "ask": [
      { "capability": "mcp:filesystem:write_file" },
      { "capability": "mcp:filesystem:delete_file" }
    ],
    "deny": []
  }
}

Create a process Routines