[FEATURE] Agent SDK: Add HTTP/WebSocket transport for web application backends

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

The Agent SDK currently supports two consumption modes:

1. CLI (claude -p): stdin/stdout, suitable for scripts and CI/CD
2. Library (Python/TypeScript query()): in-process, suitable for server-side applications

Neither mode is designed for web application backends that need to serve multiple concurrent browser clients. To build a web interface for Claude Code agents today, developers must:

• Wrap the SDK's async iterator in a WebSocket/SSE handler
• Bridge canUseTool callbacks across network boundaries (SDK callback -> HTTP -> browser -> HTTP -> SDK response)
• Manage session lifecycle across HTTP requests
• Handle reconnection and message replay

This gap has led third-party projects to bypass the SDK entirely and reverse-engineer internal protocols (e.g., the hidden --sdk-url WebSocket flag) to get a web-compatible transport layer.

Proposed Solution

Add an optional HTTP/WebSocket transport mode to the Agent SDK that exposes agent sessions as network endpoints. Something like:

import { serve } from "@anthropic-ai/claude-agent-sdk/server";

const server = serve({
  port: 3456,
  options: {
    allowedTools: ["Read", "Edit", "Bash"],
    permissionMode: "default",
  },
  // canUseTool requests are forwarded to the connected client
  // Streaming events are forwarded in real-time
});

Or a lower-level adapter that integrates with existing HTTP frameworks:

import { createSessionHandler } from "@anthropic-ai/claude-agent-sdk/http";

app.ws("/agent/:sessionId", createSessionHandler({
  options: { allowedTools: ["Read", "Edit", "Bash"] },
}));

Key capabilities:

• WebSocket or SSE transport for streaming events to browsers
• Permission requests forwarded to connected clients with response channel
• Session create/resume/list via HTTP endpoints
• Message replay on reconnection
• Multiple concurrent sessions

Alternative Solutions

1. Better documentation of stdin/stdout protocol: Document --input-format stream-json so developers can wrap the CLI process with a WebSocket bridge. Works but requires process management, is less efficient, and the stdin protocol isn't fully documented.

1. Official example app: Provide a reference implementation showing how to bridge query() to WebSocket clients. This works with the current SDK but requires each developer to solve the same bridging problems.

1. Status quo: Developers continue building custom bridges or reverse-engineering internals. This leads to fragile, unsupported implementations.

Priority

• [ ] Critical - Blocking my work
• [ ] High - Significant impact on productivity
• [x] Medium - Would be very helpful
• [ ] Low - Nice to have

Feature Category

• [ ] CLI commands and flags
• [ ] Interactive mode (TUI)
• [ ] File operations
• [ ] API and model interactions
• [ ] MCP server integration
• [ ] Performance and speed
• [ ] Configuration and settings
• [x] Developer tools/SDK
• [ ] Documentation
• [ ] Other

Use Case Example

Team development dashboard: A team wants a shared web interface where developers can:

1. Open https://internal-tool.company.com in their browser
2. Launch a Claude Code agent session with a specific working directory
3. See streaming responses in real-time
4. Approve/deny tool calls through the browser UI
5. Multiple developers can have concurrent sessions

Today this requires either:

• Reverse-engineering the --sdk-url WebSocket protocol (fragile, unsupported)
• Building a custom bridge between query() and WebSocket (significant boilerplate)
• Using claude -p with custom stdin/stdout handling (underdocumented, process management overhead)

With an HTTP transport, the server side reduces to a few lines of configuration.

Additional Context

The internal --sdk-url flag already implements exactly this pattern: a WebSocket transport for the agent protocol. The existence of this internal feature suggests Anthropic has already solved the engineering problem. Making a supported version of this transport available through the Agent SDK would channel third-party efforts toward a stable interface.

Anthropic's own "Claude Code on the web" uses a similar architecture (isolated VM with network transport to browser). A lighter-weight, self-hosted version of this pattern would serve the developer community.