# Use Runtime with your AI framework

Keep your framework's model and agent loop; give it a tool that runs in a Runtime
sandbox. The application creates the sandbox, binds the tool to it, and stops it
when the work ends. The model chooses the command, never the sandbox or the
tenant.

These examples cover execution tools, not automatic replacement of a framework’s
built-in local shell or filesystem. Disable conflicting local tools when needed.
Inspect exit codes as well as API success.

## Vercel AI SDK

```ts
import { jsonSchema, tool } from "ai";
import type { Sandbox } from "withruntime";

export function runtimeTool(sandbox: Sandbox) {
  return tool({
    description:
      "Run a shell command in the application's Runtime sandbox and get exitCode, stdout and stderr.",
    inputSchema: jsonSchema<{ command: string }>({
      type: "object",
      additionalProperties: false,
      properties: { command: { type: "string", description: "Runs under bash -c." } },
      required: ["command"],
    }),
    execute: ({ command }) => sandbox.exec(command),
  });
}
```

Pass `{ runtime: runtimeTool(sbx) }` as the call's `tools`.

## OpenAI Agents SDK

```ts
import { z } from "zod";
import { tool } from "@openai/agents";
import type { Sandbox } from "withruntime";

export function runtimeTool(sandbox: Sandbox) {
  return tool({
    name: "runtime_exec",
    description:
      "Run a shell command in the application's Runtime sandbox and get exitCode, stdout and stderr.",
    parameters: z.object({ command: z.string().min(1) }),
    execute: async ({ command }) => JSON.stringify(await sandbox.exec(command)),
  });
}
```

Add `runtimeTool(sbx)` to the agent's `tools`.

## Claude Agent SDK

```ts
import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";
import type { Sandbox } from "withruntime";

export function runtimeServer(sandbox: Sandbox) {
  return createSdkMcpServer({
    name: "runtime",
    version: "0.2.0",
    tools: [
      tool(
        "runtime_exec",
        "Run a shell command in the application's Runtime sandbox and get exitCode, stdout and stderr.",
        { command: z.string().min(1) },
        async ({ command }) => ({
          content: [{ type: "text", text: JSON.stringify(await sandbox.exec(command)) }],
        }),
      ),
    ],
  });
}

/** The same tool in a Messages API loop: run sandbox.exec(input.command). */
export const messagesTool = {
  name: "runtime_exec",
  description:
    "Run a shell command in the application's Runtime sandbox and get exitCode, stdout and stderr.",
  input_schema: {
    type: "object" as const,
    properties: { command: { type: "string" } },
    required: ["command"],
    additionalProperties: false,
  },
};
```

Pass `runtimeServer(sbx)` as `mcpServers.runtime` and allow only
`mcp__runtime__runtime_exec`.

## LangChain

```python check
from langchain_core.tools import tool
from withruntime import Sandbox


def runtime_tool(sandbox: Sandbox):
    @tool
    def runtime_exec(command: str) -> dict:
        """Run a shell command in the application's Runtime sandbox; returns exitCode, stdout and stderr."""
        return sandbox.exec(command).to_dict()

    return runtime_exec
```

Pass `runtime_tool(sbx)` to `create_agent` or a LangGraph `ToolNode`.

## Use Runtime's MCP server instead

Coding agents can connect to Runtime's own tools, which cover files, processes
and every other product: see [MCP](./mcp). OpenAI's Responses API and
Anthropic's Messages API can also call a hosted MCP server; the provider must be
able to reach `https://api.withruntime.com/mcp`.

## What was verified

These samples are typechecked against the current SDK on every build. On
22 September 2026 the same four integrations, written for SDK 0.1.0, passed a
model-driven workflow through the public API and real sandboxes: write input,
compute, handle a nonzero exit, read the output back, confirm shutdown. Those were
bounded single-workflow checks, not universal framework compatibility or
performance guarantees.

Official references checked 18 September 2026:
[Vercel tools](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling),
[OpenAI tools](https://developers.openai.com/api/docs/guides/tools),
[OpenAI MCP](https://developers.openai.com/api/docs/guides/tools-connectors-mcp),
[Claude Agent SDK custom tools](https://platform.claude.com/docs/en/agent-sdk/custom-tools),
[LangChain tools](https://docs.langchain.com/oss/python/langchain/tools).