createActionHandler
Serve agents' tools, hooks, and flow functions as an Action endpoint.
import { createActionHandler } from "@nylorun/agents";Guides: Action endpoints, App server.
createActionHandler
createActionHandler(options: ActionHandlerOptions): ActionHandlerReturns one HTTP handler for the agents' Actions. The Runtime POSTs each tool
call, hook, and flow fn, verify, or tool step to it. Each request's
delivery token (Nylorun-Signature) is verified before any code runs: it must
be signed by the Tenant's key, for this Tenant, URL, Action, generation, and
exact body. Sandbox tools run in the Runtime instead.
const actions = createActionHandler({ agents, url, onError: console.error });
createServer(actions.node).listen(3001);
await actions.register({ url });ActionHandlerOptions
| Name | Type | Required | Description |
|---|---|---|---|
agents | readonly (AgentSource | BuiltWorkflow)[] | Yes | Agents and flow agents served. Agents they embed are served too. |
client | AgentsClient | Promise<AgentsClient> | No | Application client for register, and for reading public keys when runtime is unset. Default: createClient(). |
runtime | { url: string; tenant: string; fetch? } | No | Where to read the Tenant's public keys without a key. Set it for a process that only serves Actions. |
jwks | { keys: readonly JsonWebKey[] } | No | The Tenant's public keys, instead of reading them from the Runtime. |
url | string | No | The registered URL every delivery token must name. Default: the URL passed to register in this process. |
implementationVersion | string | No | Registered with each endpoint. Default: NYLORUN_IMPLEMENTATION_VERSION, then dev. |
onError | (error: unknown) => void | No | Receives errors answered with a status instead of thrown. |
waitUntil | (work: Promise<unknown>) => void | No | Keeps a background tool's work alive after its 202 on platforms that end work with the response. A Node server needs nothing. |
ActionHandler
| Member | Type | Description |
|---|---|---|
fetch | (request: Request) => Promise<Response> | Web-standard handler: Hono, Next.js route handlers, Workers, Bun, Deno. |
node | Node request listener | The same handler for node:http and Express. |
register | (options: RegisterOptions) => Promise<EndpointPingResponse[]> | Saves definitions, registers url for every served agent, and pings each through the Runtime. |
register needs an application key and a Runtime with the action-endpoints
feature; it refuses an older Runtime before sending anything.
RegisterOptions
| Name | Type | Required | Description |
|---|---|---|---|
url | string | Yes | The URL the Runtime calls, e.g. http://localhost:3001/nylorun/actions. |
saveDefinitions | boolean | No | Save the definitions first. Default true. |
timeoutMs | number | No | How long one inline delivery may take. Default 60 000; at most 840 000. |
maxConcurrent | number | No | In-flight deliveries per agent. Default 16. |
signal | AbortSignal | No | Aborts registration. |
Responses
| Status | When |
|---|---|
200 | The outcome, tagged with Nylorun-Outcome: 1, or a ping answer. |
400 | The body is not an Action delivery. |
202 | A background: true tool; the handler heartbeats and posts the result itself. |
401 | The delivery token is missing, invalid, or for another delivery. |
404 | The agent or tool is not served here. |
405 | Any method other than POST. |
409 | A flow Action for another version of the flow. The Runtime retries. |
503 | Signed with a key the handler has not seen yet, just after a rotation. The Runtime retries. |
Delegation limits
Agents used as tools cannot declare approval. ctx.ask, ctx.approve,
ctx.sleep, and ctx.waitFor inside a delegated agent fail with
delegation.interaction-unsupported.