# executor (/docs/reference/agents/executor)



```ts
import { connectAgents } from "@nylorun/agents/executor";
```

Guides: [Executors](/docs/run/executors), [App server](/docs/deploy/app-server#executors).

## `connectAgents` [#connectagents]

```ts
connectAgents(options: ConnectOptions): AgentConnection
```

Saves every definition, registers an executor for each runnable, and opens an
authenticated event stream. When the Runtime offers an action, the executor
claims it, runs your implementation, and returns the result. It runs agent
tools and hooks, and workflow tool, `fn`, and `verify` nodes. Sandbox tools
run in the Runtime instead.

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `agents` | `readonly (AgentSource \| BuiltWorkflow<JsonValue, JsonValue>)[]` | Yes | Every runnable to serve. Agents used as tools are served with their parent. |
| `runtime` | `Destination \| undefined` | No | `{ url, tenant, key }`. Default: environment, then project link. |
| `implementationVersion` | `string \| undefined` | No | Default `NYLORUN_IMPLEMENTATION_VERSION`, then `"dev"`. |
| `application` | `AgentsClient \| undefined` | No | Use an existing application client instead of resolving one. |
| `onError` | `((error: unknown) => void) \| undefined` | No | Receives connection and execution errors. |

**Returns** an `AgentConnection`:

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `ready` | `Promise<void>` | Yes | Settles after registration, discovery, and the authenticated stream are up. |
| `close` | `() => Promise<void>` | Yes | Stops subscriptions and leases. Running user code receives an `AbortSignal`. |

**Throws** (via `ready`) `ConnectionError` when no connection is found, and
`IncompatibleRuntimeError` on version skew.

```ts
const connection = connectAgents({ agents, onError: console.error });
await connection.ready;
```

## Credentials [#credentials]

With an application key, `PUT /v1/executors` registers a derived token for each
`(application key, Tenant, runnable id)`. Tokens are never stored. Claims send
only `{ requestId, implementationVersion }`. With `NYLORUN_EXECUTOR_KEY`, the
executor uses that pre-provisioned, single-runnable credential.

## Delegation limits [#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`.

## `deriveExecutorToken` [#deriveexecutortoken]

Computes the same derived executor token the SDK registers. Most apps never
call it directly.