Runlayer Hooks Python SDK

Python SDK companion to @runlayer/hooks-sdk.

Configure

export RUNLAYER_BASE_URL="https://your-runlayer-instance.com"
export RUNLAYER_API_KEY="rl_..."

Agent account auth is also supported:

export RUNLAYER_BASE_URL="https://your-runlayer-instance.com"
export RUNLAYER_AGENT_CLIENT_ID="client_..."
export RUNLAYER_AGENT_CLIENT_SECRET="..."

Optional OBO subject fields:

export RUNLAYER_AGENT_SUBJECT_TOKEN="user@example.com"
export RUNLAYER_AGENT_SUBJECT_TOKEN_TYPE="urn:runlayer:token-type:user-email"

Optional runtime controls:

Usage

from runlayer_sdk import RunlayerClient

runlayer = RunlayerClient.from_env(client_version="my-agent/1.0.0")


def run_local_tool(tool_input: dict[str, object]) -> str:
    return "tool output"


output = runlayer.run_tool(
    execute=run_local_tool,
    session_id="session-id",
    tool_input={"command": "cat README.md"},
    tool_name="Bash",
    tool_type="shell",
)

Use tool_enforcement to skip Runlayer-owned MCP tools or proxy URLs:

runlayer = RunlayerClient.from_env(
    tool_enforcement={
        "ignored_mcp_server_names": ["github-preview"],
        "skip_runlayer_mcp_proxy_urls": True,
    }
)

RunlayerClient exposes:

• emit_event
• before_tool
• after_tool
• run_tool
• should_enforce_tool

The package also exports send_runlayer_preflight.

Troubleshooting: sessions not appearing

Lifecycle hooks send events best-effort and do not raise on their own. If the server accepts an event but does not record it, it responds with status: "ignored" and a reason. The client logs a one-time warning to stderr for the actionable reasons so a misconfiguration is not silent:

• client_not_enabled — the SDK session-monitoring client is off for this workspace. Enable the client (and any required SDK toggle) in Runlayer settings. This is a separate switch from tool enforcement, so both must be on to get full session + tool telemetry.
• actor_unresolved — the request authenticated but Runlayer could not map it to a user/agent. Organization-level API keys are not supported for session attribution. Use a personal API key (RUNLAYER_API_KEY) or agent-account credentials (RUNLAYER_AGENT_CLIENT_ID / RUNLAYER_AGENT_CLIENT_SECRET).

Set RUNLAYER_HOOK_DEBUG=1 to also log transient ignore reasons and network failures. Run send_runlayer_preflight() for an explicit check.

Framework tool adapters

Dependency-free adapters wrap common tool dictionary shapes:

• with_runlayer_vercel_ai_tool
• with_runlayer_vercel_ai_tools
• with_runlayer_openai_agents_tool
• with_runlayer_google_adk_tool
• run_runlayer_adapter_tool

Claude Agent SDK hooks

Use the adapter helpers when a Python agent runtime wants the same Claude Agent SDK hook output shapes as the Hooks TypeScript SDK:

from runlayer_sdk import RunlayerClient, create_claude_agent_sdk_hooks

runlayer = RunlayerClient.from_env()
hooks = create_claude_agent_sdk_hooks(runlayer, include_stop=False)

The adapter exports:

• create_claude_agent_sdk_hooks
• emit_claude_agent_sdk_transcript_stop
• claude_agent_sdk_assistant_message_to_transcript_line
• tool_type_from_name

TypeScript-style camelCase aliases are also available for SDK parity.