Skip to main content
The Runlayer Hooks SDK wires custom agent runtimes into Runlayer’s hook enforcement and telemetry pipeline. It streams an agent’s full conversation — prompts, reasoning, tool calls, and responses — into Runlayer Sessions, and lets Runlayer observe, rewrite, or block the tool calls your agent executes directly. The same SDK ships for TypeScript and Python — use the language switch on any code sample to flip the whole page.
This SDK does not replace MCP client setup. To connect an agent framework (Claude Agent SDK, Vercel AI SDK, OpenAI Agents SDK, Google ADK) to Runlayer-hosted MCP servers, see Agent Frameworks. Use the adapters on this page for tools your own process executes locally. Vercel Eve uses both a native lifecycle hook and a session-aware Runlayer MCP connection.

Copy prompt

Paste this into your coding agent to wire Runlayer into an existing agent project:

Capabilities

  • lifecycle telemetry for session, prompt, and stop events
  • pre-tool enforcement with optional argument rewriting
  • post-tool output scanning and blocking
  • failed tool telemetry
  • direct MCP source enforcement
  • preflight session emission for ingestion checks
  • transcript-bearing Stop events for assistant reasoning extraction
  • Vercel Eve native runtime lifecycle telemetry
  • framework tool wrappers for Claude Agent SDK, Vercel AI SDK, OpenAI Agents SDK, and Google ADK

Getting started

1

Install the package

Install the agent framework package you use separately, such as @anthropic-ai/claude-agent-sdk, ai, @openai/agents, or @google/adk.Verified TypeScript framework versions as of 2026-07-10 (using the repository’s seven-day minimum release age):
2

Create credentials

Create a Runlayer user API key in Settings → Personal API keys, then set:
For custom or cloud installations that share one organization API key (Settings → Organization API keys, with the AI Watch scan role), also name the Runlayer user each deployment runs as:
Sessions and enforcement are attributed to that user. The identity can be a service user provisioned just for the deployment; events sent before the user exists in the workspace are buffered and replayed once it does.To authenticate as an agent account instead, set:
The SDK mints an agent token with client_credentials and, when an OBO subject is configured, exchanges it via RFC 8693 token exchange (urn:ietf:params:oauth:grant-type:token-exchange); both tokens are cached and refreshed internally. Do not configure or pass a pre-minted bearer token.For agent tokens, also set:
3

Confirm the SDK session monitoring client

Generic SDK integrations attribute events to the first-party Hooks SDK client (typescript-sdk or python-sdk). Dedicated adapters retain their runtime identity; the Eve adapter uses vercel-eve. In Runlayer, open Settings → Agent session monitoring → Full session scanning APIs → Hook clients and confirm the matching session monitoring client is enabled before testing. Newly supported clients such as Vercel Eve are enabled by default; disable a client explicitly if its full session content should not be collected. If the client option is missing, ask a Runlayer admin to enable SDK session monitoring for the workspace.
4

Run preflight

Vercel Eve uses its native event vocabulary. Skip this generic SDK preflight for Eve; finish the Vercel Eve setup, run one real Eve turn, and verify that session in Runlayer instead.
Verify that Runlayer receives hook events before invoking a real model.
Preflight sends a strict SessionStart, UserPromptSubmit, and Stop sequence for a synthetic session. If any request fails, or if session monitoring is not enabled for this workspace, the helper throws. Open the printed session to confirm it appears in Runlayer.

Configuration

Optional environment variables (identical across languages):
Default request timeouts differ by SDK. TypeScript uses a single 10000 ms default. Python uses 30000 ms for enforcement and tool lifecycle hooks, 5000 ms for lifecycle event hooks, and 10000 ms for direct endpoint calls. Override either with RUNLAYER_HOOK_TIMEOUT_MS.

Runtime safety

Runlayer enforcement is by default. If pre-tool, post-tool, or direct MCP source enforcement cannot reach Runlayer, the SDK treats the call as blocked. Lifecycle telemetry is best-effort unless a helper documents strict behavior, such as preflight and transcript Stop emission. Every hook request uses a timeout, and tool output is capped before upload. Failed tool outputs include bounded stdout, stderr, and output fields with truncation metadata when available, so Runlayer can scan failure context without the SDK uploading unbounded logs. The SDK skips pre-tool and post-tool enforcement for Runlayer’s own MCP server names (runlayer, runlayer-plugin, and onelayer) and for MCP calls whose tool URL points at a Runlayer proxy URL. Third-party MCP tools remain enforced by default. For custom runtimes, use the exported shouldEnforceTool / should_enforce_tool helper or the client’s tool-enforcement option so new adapters make the same decision consistently. The base URL must use https:// unless insecure transport is explicitly enabled for a trusted local endpoint.

Vercel Eve

Vercel Eve exposes native runtime hooks for its durable stream lifecycle. Use the Runlayer Eve adapter to send that lifecycle directly to Sessions, without an external relay or polling process. Install the Hooks SDK in the Eve project:
Create the native hook:
Set the Agent Account environment variables shown under Create credentials. For OBO attribution by Runlayer user ID, set:
In Runlayer’s Agent Account setup guide, select Vercel Eve and create the generated agent/connections/runlayer.ts. It combines renewable client_credentials/OBO authentication with this session-aware header:
The callback runs with the active Eve session context. One Eve session.id, including all of its turns, maps to one Runlayer Session, and every Runlayer MCP call correlates with the hook lifecycle from the first request. Do not generate a second session identifier or replace the generated renewable authentication with a static bearer token. Pass every Eve MCP connection slug in mcpConnectionNames, including the Runlayer connection. Eve’s native event only carries a qualified tool name, and dynamic local tools may also contain __; the explicit slug list lets Runlayer distinguish MCP tools from local tools without guessing. Run one real Eve turn and open it in Runlayer Sessions to smoke-test this adapter. sendRunlayerPreflight() emits the generic SDK lifecycle vocabulary, not Eve’s native events, so it is not the Eve verification path.
Eve treats a thrown hook as a real turn failure. The Runlayer adapter catches and logs lifecycle delivery failures, so Session telemetry is fail-open and a Runlayer outage does not fail the Eve turn. This does not make MCP enforcement fail-open: calls through the Runlayer proxy still use normal policies and scanning. The adapter observes Eve-local tools for Sessions but does not block them.
Built-in agent copies inherit the parent hook. Declared subagents have isolated hook directories, so install or re-export the Runlayer hook in each declared subagent that needs full child visibility. Remote subagents need the hook in their own deployment. The parent Session still records the child lifecycle.

Framework adapters

Wrap the tools your runtime executes so Runlayer can enforce them. Pick your harness — the language toggle inside each example still controls the whole page.
Pass Runlayer hooks into Claude Agent SDK’s query options.
Use includeStop: false / include_stop=False when you emit a transcript-bearing Stop manually. That lets Runlayer extract assistant thinking or reasoning blocks from the completed transcript instead of receiving a bare lifecycle stop.
Each query() call starts a new Claude Agent SDK session with a fresh session_id, and Runlayer records each session id as a separate session. To keep a multi-prompt conversation in a single Runlayer session, resume the previous session on follow-up calls (leave forkSession / fork_session unset so the session id is preserved):
Emit the transcript Stop after each run as usual — repeated Stop events with the same session id land in the same Runlayer session.

Direct MCP source enforcement

Use direct MCP source enforcement when a custom agent can call MCP servers without going through the Runlayer proxy.
If Runlayer denies the source, the call throws RunlayerBlockedError.
The Python direct MCP source route posts to the Cursor hook route and currently requires user API-key auth. Configure RUNLAYER_API_KEY for this client; agent-account bearer auth is supported for lifecycle and tool hooks, but not this direct route.

API reference

RunlayerClient.fromEnv(options?)

Creates a client from RUNLAYER_BASE_URL plus one auth source: RUNLAYER_API_KEY or RUNLAYER_AGENT_CLIENT_ID / RUNLAYER_AGENT_CLIENT_SECRET. With API key auth, RUNLAYER_USER_EMAIL names the user attributed when the key is an organization key.
string
Client name sent to Runlayer. Defaults to RUNLAYER_HOOK_CLIENT or typescript-sdk.
string
Version string for your agent runtime; used for audit-log attribution.
string
default:"closed"
closed blocks on enforcement outages; open allows on outages.
number
default:"10000"
Per-request timeout in milliseconds.
object
Tool filtering shared by generic wrappers and framework adapters.
  • createClaudeAgentSdkHooks(client, options?) — Claude Agent SDK hook map.
  • createVercelEveHook(client, options?) — fail-open Vercel Eve native runtime hook.
  • sendRunlayerPreflight(client, options?) — strict synthetic lifecycle sequence.
  • emitClaudeAgentSdkTranscriptStop(client, options) — strict transcript Stop.
  • runTool(options) — run a custom tool through pre/post enforcement.
  • withRunlayerVercelAiTool / withRunlayerVercelAiTools / withRunlayerOpenAIAgentsTool / withRunlayerGoogleAdkTool — adapter helpers.
  • enforceMcpSource(options) — validate a direct MCP source.

Troubleshooting

Enable the matching SDK session monitoring client (TypeScript SDK or Python SDK) in Settings → Agent session monitoring, then rerun preflight. If you cannot see the client option, ask a Runlayer admin to enable SDK session monitoring for the workspace.
Use the session URL first. If you only have an ID, use the Runlayer session ID in the Sessions URL or search field. The synthetic external session ID emitted by your agent is useful for logs but may not be the best lookup key.
Confirm you constructed the client with the same credentials used for preflight, and wrap local tool execution with a framework adapter or runTool / run_tool. Preflight only proves lifecycle ingestion; it does not wrap your tools by itself.
The request authenticated, but Runlayer could not map it to a user. With an organization API key, set RUNLAYER_USER_EMAIL (or the userEmail / user_email client option) to the Runlayer user the deployment runs as. If that user does not exist in the workspace yet, session events are buffered and replayed once it is created; tool enforcement stays inactive until then. Otherwise use a personal API key or agent-account credentials.
The applicable MDM configuration disables session reporting. Ask a Runlayer administrator to enable Sessions in that MDM configuration. Tool enforcement remains active while session reporting is disabled.