Claude AgentSDK + Bedrock + Headroom = supported ?

[jo-me]

Hi,
Is running the programmatic Claude Agent SDK against AWS Bedrock through the Headroom proxy a supported combination?

Wrapping Claude CLI with Bedrock seems to work as far as I understand, but I couldn't get the Agent SDK (against Bedrock) to work with headroom proxy.

Environment

• headroom-ai 0.30.0
• claude-agent-sdk 0.2.110, Python 3.12, Linux x86_64
• AWS Bedrock us-east-1

Jochen Mehlhorn jochen.mehlhorn@mercedes-benz.com, Mercedes-Benz Tech Innovation GmbH

Provider Information

[ymxlx]

Short answer: yes, it should work the same way as the Claude Code CLI recipe, and the reason is worth knowing since it explains why it wasn't working for you.

The Agent SDK doesn't talk to Bedrock (or Anthropic, or Headroom) on its own — it spawns the actual claude CLI binary as a subprocess and passes through your process's environment (see subprocess_cli.py in claude-agent-sdk-python, it merges os.environ with anything you set via ClaudeAgentOptions.env). So whatever env vars make the CLI recipe work will make the SDK work too, since under the hood it's still the CLI making the request.

The repo has a doc for exactly this setup at docs/claude-code-bedrock-headroom.md, and the key gotcha is this one:

CLAUDE_CODE_USE_BEDROCK=0

If that's set to 1 (or unset with some other Bedrock-mode flag active), Claude Code calls Bedrock directly via the AWS SDK and completely bypasses ANTHROPIC_BASE_URL — proxy never sees a byte. That's almost certainly why it "seems to work" for the CLI-wrapping case in your notes but not for the SDK.

So for the Agent SDK, set (either via the process env or ClaudeAgentOptions(env={...})):

CLAUDE_CODE_USE_BEDROCK=0
ANTHROPIC_BASE_URL=http://127.0.0.1:8787   # your headroom proxy
ANTHROPIC_API_KEY=headroom                  # value is ignored, just needs to be present
ANTHROPIC_MODEL=claude-opus-4-6

with the proxy itself started in Bedrock mode: headroom proxy --port 8787 --backend bedrock --region us-east-1.

If it's still not routing through the proxy after that, check the proxy's dashboard//stats endpoint for incoming requests — if it's empty, something in your env is still steering the SDK to direct Bedrock mode rather than the proxy.

[jo-me]

Thanks @yehudaLevy. Your answer clarifies why it did not work at first for me.
But with this setup in place prompt caching breaks completely due to a bug in headroom itself. I So not much benefit yet until #1345 is fixed.