Built-in Handlers

The Orch8 engine ships with eighteen built-in step handlers covering HTTP integrations, AI orchestration, control flow, and state management. Custom handlers are registered in the handler registry; the built-ins below are always available.

HTTP & Integration

Handlers for making outbound HTTP and gRPC calls to external services, APIs, and tool endpoints.

http_request

Makes an HTTP request to any URL. Supports GET, POST, and PUT methods. The handler automatically retries on 5xx server errors using the step's retry configuration.

JSON

1// GET request with custom headers
2{
3  "type": "step",
4  "id": "fetch_user",
5  "handler": "http_request",
6  "params": {
7    "url": "https://api.example.com/users/{{context.data.user_id}}",
8    "method": "GET",
9    "headers": {
10      "Authorization": "Bearer {{context.config.api_token}}"
11    },
12    "timeout_ms": 10000
13  }
14}
15
16// POST request with a JSON body
17{
18  "type": "step",
19  "id": "create_order",
20  "handler": "http_request",
21  "params": {
22    "url": "https://api.example.com/orders",
23    "method": "POST",
24    "body": {
25      "product_id": "{{context.data.product}}",
26      "quantity": 1
27    },
28    "headers": {
29      "Content-Type": "application/json"
30    }
31  }
32}

Parameter	Type	Required	Description
url	string	Yes	The target URL. Supports template expressions.
method	string	No	HTTP method: GET, POST, or PUT. Defaults to GET.
body	object	No	Request body, serialised as JSON.
headers	object	No	Key-value map of HTTP headers.
timeout_ms	number	No	Request timeout in milliseconds. Defaults to 30000.

Note

5xx responses are treated as retryable errors. 4xx responses fail the step immediately without retry.

tool_call

Sends a structured tool invocation to an HTTP endpoint. Designed for AI-agent tool-use patterns where the LLM returns a tool name and arguments, and a separate step executes the actual call.

JSON

1{
2  "type": "step",
3  "id": "run_tool",
4  "handler": "tool_call",
5  "params": {
6    "url": "https://tools.internal/execute",
7    "tool_name": "search_database",
8    "arguments": {
9      "query": "{{steps.plan.output.search_query}}",
10      "limit": 10
11    },
12    "method": "POST",
13    "headers": {
14      "X-Tenant": "{{context.tenant_id}}"
15    },
16    "timeout_ms": 15000
17  }
18}

Parameter	Type	Required	Description
url	string	Yes	The tool endpoint URL.
tool_name	string	No	Identifier for the tool being invoked.
arguments	object	No	Payload passed to the tool as its input.
method	string	No	HTTP method. Defaults to POST.
headers	object	No	Additional HTTP headers.
timeout_ms	number	No	Request timeout in milliseconds. Defaults to 30000.

grpc:// (gRPC handlers)

Call any gRPC service as a workflow step by prefixing the handler with grpc://. The engine sends step params as JSON and receives JSON back. Retry, timeout, and circuit breaker all apply identically to gRPC handlers -- no worker polling is needed.

JSON

1{
2  "type": "step",
3  "id": "classify",
4  "handler": "grpc://classifier:50051/Classifier.Predict",
5  "params": {
6    "text": "{{context.data.input}}"
7  },
8  "timeout": 30000,
9  "retry": {
10    "max_attempts": 2,
11    "initial_backoff": 1000,
12    "max_backoff": 5000,
13    "backoff_multiplier": 2.0
14  }
15}

The handler string follows the pattern grpc://host:port/Service.Method. The engine resolves the host via standard DNS, connects over HTTP/2, and transparently maps JSON params to the Protobuf request message.

AI & Agent

Handlers for calling language models, delegating decisions to humans, and letting agents modify their own execution plan at runtime.

llm_call

Built-in handler for calling language model APIs. Supports ten providers out of the box. The handler normalises the response into a consistent output shape regardless of provider.

JSON

1{
2  "type": "step",
3  "id": "summarise",
4  "handler": "llm_call",
5  "params": {
6    "provider": "anthropic",
7    "model": "claude-sonnet-4-20250514",
8    "system_prompt": "You are a concise summariser.",
9    "prompt": "Summarise the following text:
10
11{{context.data.article}}",
12    "temperature": 0.3,
13    "max_tokens": 512
14  }
15}

Parameter	Type	Required	Description
provider	string	Yes	LLM provider. See supported list below.
model	string	Yes	Model identifier (provider-specific).
prompt	string	Yes	The user/input prompt sent to the model.
system_prompt	string	No	System-level instruction for the model.
temperature	number	No	Sampling temperature (0.0 - 2.0). Defaults to 1.0.
max_tokens	number	No	Maximum tokens in the response.

Supported providers: openai, anthropic, gemini, deepseek, qwen, perplexity, groq, together, mistral, openrouter.

Warning

Do not commit API keys in a sequence definition. Prefer a tenant-scoped credential or let an external worker read secrets from its deployment secret manager. If a secret must be supplied throughcontext.config, enable storage encryption and restrict handler context access.

human_review

Pauses the running instance and waits for an external human signal before continuing. This is equivalent to wait_for_input but named for agent contexts where a human must approve, reject, or augment the agent's plan.

JSON

1{
2  "type": "step",
3  "id": "approval",
4  "handler": "human_review",
5  "params": {
6    "prompt": "Review the generated report before publishing."
7  }
8}

Tip

While waiting, the instance uses zero scheduler resources. It resumes instantly when the signal arrives via the REST API or a send_signal call.

self_modify

Injects new blocks into the running instance at runtime. An LLM or orchestration layer returns a list of tool calls as JSON; the handler inserts those as real execution steps. You can also inject blocks externally via the REST API.

JSON

1// Step 1: LLM decides what to do next
2{
3  "type": "step",
4  "id": "analyze_task",
5  "handler": "llm_call",
6  "params": {
7    "provider": "openai",
8    "model": "gpt-4o",
9    "prompt": "Return a JSON array of tool calls for: {{context.data.request}}"
10  }
11}
12
13// Step 2: Inject the LLM's tool calls as real steps
14{
15  "type": "step",
16  "id": "inject_tools",
17  "handler": "self_modify",
18  "params": {
19    "blocks": "{{steps.analyze_task.output.tool_calls}}",
20    "position": 0
21  }
22}
23
24// External injection via REST API
25// POST /instances/{id}/inject-blocks
26// {
27//   "blocks": [{ "type": "step", "id": "new_step", "handler": "fetch_data", "params": { "url": "..." } }],
28//   "inject_after": "current"
29// }

Parameter	Type	Required	Description
blocks	array	Yes	JSON array of block definitions to inject.
position	number	No	Insertion point: 0 = before the next unexecuted block. Omit to append at the end.

Control Flow

Handlers for pausing execution, failing intentionally, asserting conditions, and coordinating between workflow instances.

sleep

Pauses execution for a specified duration. The engine reschedules the step rather than blocking a thread, so sleeping steps consume zero resources.

params.duration_ms belongs to the explicit sleep handler. A block's delay.duration is a scheduling delay before that block starts; it does not invoke this handler.

JSON

1{
2  "type": "step",
3  "id": "wait_before_retry",
4  "handler": "sleep",
5  "params": {
6    "duration_ms": 5000
7  }
8}

Parameter	Type	Required	Description
duration_ms	number	Yes	How long to sleep in milliseconds.

noop

Does nothing and returns an empty object. Useful as a placeholder step, a delay-only step (when combined with a timeout), or a join point in complex control-flow graphs.

JSON

1{
2  "type": "step",
3  "id": "checkpoint",
4  "handler": "noop"
5}

fail

Immediately fails the step with a custom error message. Use this to short-circuit execution when a precondition is not met, or to mark a branch as explicitly errored.

JSON

1{
2  "type": "step",
3  "id": "reject_invalid",
4  "handler": "fail",
5  "params": {
6    "message": "Input validation failed: missing required field 'email'"
7  }
8}

Parameter	Type	Required	Description
message	string	Yes	Error message attached to the step failure.

assert

Evaluates a condition expression and fails the step if it resolves to false. Useful for guard clauses and data-quality checks within a workflow.

JSON

1{
2  "type": "step",
3  "id": "check_balance",
4  "handler": "assert",
5  "params": {
6    "condition": "{{context.data.balance}} >= 100",
7    "message": "Insufficient balance: need at least 100, got {{context.data.balance}}"
8  }
9}

Parameter	Type	Required	Description
condition	string	Yes	Expression that must evaluate to true.
message	string	No	Error message if the assertion fails.

emit_event

Fires an event trigger to spawn a new workflow instance within the same tenant. Supports deduplication to prevent duplicate instances from identical events.

JSON

1{
2  "type": "step",
3  "id": "notify_downstream",
4  "handler": "emit_event",
5  "params": {
6    "trigger_slug": "order_completed",
7    "dedupe_key": "{{context.data.order_id}}",
8    "dedupe_scope": "tenant"
9  }
10}

Parameter	Type	Required	Description
trigger_slug	string	Yes	The slug of the trigger to fire.
dedupe_key	string	No	Deduplication key. If a matching event was already emitted, this one is skipped.
dedupe_scope	string	No	Scope for deduplication: "parent" (this instance) or "tenant" (tenant-wide).

send_signal

Sends a signal to another running instance within the same tenant. Use this to resume paused instances, pass data between workflows, or coordinate multi-instance processes.

JSON

1{
2  "type": "step",
3  "id": "resume_reviewer",
4  "handler": "send_signal",
5  "params": {
6    "instance_id": "{{context.data.reviewer_instance_id}}",
7    "signal_type": "review_complete",
8    "payload": {
9      "approved": true,
10      "reviewer": "{{context.data.user_email}}"
11    }
12  }
13}

Parameter	Type	Required	Description
instance_id	string	Yes	ID of the target instance to signal.
signal_type	string	Yes	Signal type identifier the target instance is waiting for.
payload	object	No	Arbitrary data delivered with the signal.

State Management

Handlers for reading, writing, and transforming data within an instance's execution context.

set_state / get_state / delete_state

Read, write, and remove values from session-scoped state. Session state persists for the lifetime of the instance and is accessible from any step via template expressions.

JSON

1// Write a value
2{
3  "type": "step",
4  "id": "save_token",
5  "handler": "set_state",
6  "params": {
7    "key": "auth_token",
8    "value": "{{steps.login.output.token}}"
9  }
10}
11
12// Read a value
13{
14  "type": "step",
15  "id": "read_token",
16  "handler": "get_state",
17  "params": {
18    "key": "auth_token"
19  }
20}
21
22// Remove a value
23{
24  "type": "step",
25  "id": "clear_token",
26  "handler": "delete_state",
27  "params": {
28    "key": "auth_token"
29  }
30}

Parameter	Type	Required	Description
key	string	Yes	The state key to read, write, or delete.
value	any	set_state only	The value to store. Can be a string, number, object, or array.

merge_state

Merges an object into context.data. Existing keys are overwritten, new keys are added. Useful for aggregating results from parallel branches or enriching context data.

JSON

1{
2  "type": "step",
3  "id": "enrich_context",
4  "handler": "merge_state",
5  "params": {
6    "data": {
7      "enriched_at": "{{now}}",
8      "score": "{{steps.score_lead.output.score}}",
9      "tier": "{{steps.score_lead.output.tier}}"
10    }
11  }
12}

Parameter	Type	Required	Description
data	object	Yes	Key-value map to merge into context.data.

transform

Evaluates an expression against the current context and writes the result to a specified output key. Use this for data reshaping, filtering, or computed values between steps.

JSON

1{
2  "type": "step",
3  "id": "extract_emails",
4  "handler": "transform",
5  "params": {
6    "expression": "context.data.users[*].email",
7    "output_key": "email_list"
8  }
9}

Parameter	Type	Required	Description
expression	string	Yes	Expression evaluated against the current context.
output_key	string	Yes	Key where the result is stored in the step output.

query_instance

Reads another instance's context and state within the same tenant. Useful for coordination patterns where one workflow needs to inspect the progress or output of another.

JSON

1{
2  "type": "step",
3  "id": "check_parent",
4  "handler": "query_instance",
5  "params": {
6    "instance_id": "{{context.data.parent_instance_id}}"
7  }
8}

Parameter	Type	Required	Description
instance_id	string	Yes	ID of the instance to query. Must belong to the same tenant.

log

Emits a structured log entry. Logs are attached to the instance and visible in the dashboard and via the API.

JSON

1{
2  "type": "step",
3  "id": "audit_entry",
4  "handler": "log",
5  "params": {
6    "message": "Order {{context.data.order_id}} processed successfully",
7    "level": "info"
8  }
9}

Parameter	Type	Required	Description
message	string	Yes	The log message. Supports template expressions.
level	string	No	Log level: "debug", "info", or "warn". Defaults to "info".

Step Execution & Retry

Every handler -- built-in or custom -- goes through the same execution pipeline. Understanding this flow helps you configure timeouts, retries, and error handling correctly.

Step execution flow

›Check for memoized output -- if the step already ran, return cached result
›Apply timeout (if configured) -- fail the step if it exceeds the limit
›Call the handler function with a StepContext (params, context, metadata)
›On success: persist output to block_outputs with size tracking
›On retryable error: calculate next backoff (initial_ms x multiplier^attempt, capped at max), reschedule
›On permanent error: mark step as failed, propagate up the execution tree

Retry & backoff

Each step can configure independent retry behavior. All retry fields are optional and can be set per-step in the workflow definition.

Parameter	Type	Required	Description
max_attempts	number	No	Total attempts including the initial (e.g., 5 = 1 initial + 4 retries).
initial_backoff	string	No	Delay before the first retry (e.g., "1s").
max_backoff	string	No	Ceiling on backoff growth (e.g., "60s").
backoff_multiplier	number	No	Growth factor per attempt. Default: 2.0.

JSON

1{
2  "type": "step",
3  "id": "call_api",
4  "handler": "http_request",
5  "params": { "url": "https://api.example.com/data" },
6  "retry": {
7    "max_attempts": 5,
8    "initial_backoff": 1000,
9    "max_backoff": 60000,
10    "backoff_multiplier": 2.0
11  }
12}

Example progression with initial=1s, multiplier=2.0, max=60s:

1Attempt 1: immediate
2Attempt 2: wait 1s
3Attempt 3: wait 2s
4Attempt 4: wait 4s
5Attempt 5: wait 8s
6Attempt 6: wait 16s
7Attempt 7: wait 32s
8Attempt 8+: wait 60s  <- capped at max_backoff

Tip

For idempotent operations like GET requests, higher max_attempts values are safe. For non-idempotent writes, keep retries low and use assert steps to verify state before retrying.

Handler Failure Catalogue

Classify the outcome before retrying. Retryability describes the handler result, not whether repeating an external effect is safe.

Signal	Retry?	Typical cause	Action
timeout / network unavailable	Usually	Transient provider or network failure	Retry with backoff and a stable idempotency key.
HTTP 429	Yes	Provider quota or rate window	Honor Retry-After and reduce concurrency.
HTTP 5xx	Usually	Remote service failure	Retry within budget; open the circuit after repeated failures.
HTTP 4xx	No	Bad auth, input, or missing resource	Fix input or credentials before a manual retry.
schema / assertion	No	Permanent contract mismatch	Inspect the saved input and deploy a corrected sequence version.
unknown external outcome	Reconcile first	Connection ended after request dispatch	Query the provider using the idempotency key before deciding.

Ready to try Orch8?

One command to install. Then run your first local sequence.

Bash

1curl -fsSL https://orch8.io/start.sh | sh

Quick Start Guide Or skip the setup with Cloud →

Previous← Block Types NextTemplate Interpolation →

Was this helpful?