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
Stopevents 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
- TypeScript
- Python
@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.
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 transcriptStop 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:agent/connections/runlayer.ts. It combines renewable
client_credentials/OBO authentication with this session-aware header:
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.
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.- Claude Agent SDK
- Vercel AI SDK
- OpenAI Agents SDK
- Google ADK
- Custom runtime
Pass Runlayer hooks into Claude Agent SDK’s Use Emit the transcript
query options.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):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.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
- TypeScript
- Python
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 transcriptStop.runTool(options)— run a custom tool through pre/post enforcement.withRunlayerVercelAiTool/withRunlayerVercelAiTools/withRunlayerOpenAIAgentsTool/withRunlayerGoogleAdkTool— adapter helpers.enforceMcpSource(options)— validate a direct MCP source.
Troubleshooting
Preflight says SDK session monitoring is not enabled
Preflight says SDK session monitoring is not enabled
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.
Preflight prints an ID, but I cannot find the session
Preflight prints an ID, but I cannot find the session
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.
The setup script succeeds, but no tool calls are enforced
The setup script succeeds, but no tool calls are enforced
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.Events are ignored with reason actor_unresolved
Events are ignored with reason actor_unresolved
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.Events are ignored with reason sessions_disabled
Events are ignored with reason sessions_disabled
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.