Claude Agent SDK

The Claude Agent SDK is Claude Code as a Python or TypeScript library. To send an agent to the exchange, pass the exchange origin, your key and a cost cap in the environment of each query() call. Tools, hooks, subagents and sessions work as they do with Anthropic.

A query() call starts the Claude Code CLI as a subprocess with the environment that you give it. For direct Messages API calls, use the Anthropic SDK.

Print the setup with the Liquid CLI

The Liquid CLI prints the setup for the Claude Agent SDK with your model filled in. To run your own program with the exchange in its environment, use liquid exec. It sets OPENAI_BASE_URL, ANTHROPIC_BASE_URL and the keys for that process only.

curl -fsSL https://inference.ai.exchange/cli/install.sh | bash
liquid login
liquid connect claude-agent-sdk
liquid exec -- python app.py

To set up the Claude Agent SDK yourself, follow the steps below.

Before you start

• A workspace with a balance and a spend key. See API keys.

• The key exported in the environment of the process that runs the agent. It then never appears in your code:

  export LIQUID_API_KEY=sk-liquid-...
  

1. Install the SDK

The package includes the Claude Code CLI. Do not install Claude Code separately.

# Python 3.10 or newer
pip install claude-agent-sdk

# TypeScript, Node 18 or newer
npm install @anthropic-ai/claude-agent-sdk

2. Point the agent at the exchange

Pass these options to every query() call. Both versions set the same variables.

Python

import asyncio
import os

from claude_agent_sdk import ClaudeAgentOptions, query

options = ClaudeAgentOptions(
    env={
        "ANTHROPIC_API_KEY": "",
        "ANTHROPIC_AUTH_TOKEN": os.environ["LIQUID_API_KEY"],
        "ANTHROPIC_BASE_URL": "https://router.inference.ai.exchange",
        "ANTHROPIC_CUSTOM_HEADERS": "x-liquid-cap-usd: 0.50",
        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "cc.anthropic/liquid.auto",
        "ANTHROPIC_MODEL": "cc.anthropic/liquid.auto",
        "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
        "CLAUDE_CODE_AUTO_MODE_SERVER": "0",
        "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "16384",
        "CLAUDE_CODE_SUBAGENT_MODEL": "cc.anthropic/liquid.auto",
    },
    setting_sources=[],
    allowed_tools=["Read", "Glob"],
)

async def main():
    async for message in query(prompt="List the files here.", options=options):
        print(message)

asyncio.run(main())

TypeScript

import { query } from '@anthropic-ai/claude-agent-sdk'

const options = {
  env: {
    ...process.env,
    ANTHROPIC_API_KEY: '',
    ANTHROPIC_AUTH_TOKEN: process.env.LIQUID_API_KEY,
    ANTHROPIC_BASE_URL: 'https://router.inference.ai.exchange',
    ANTHROPIC_CUSTOM_HEADERS: 'x-liquid-cap-usd: 0.50',
    ANTHROPIC_DEFAULT_HAIKU_MODEL: 'cc.anthropic/liquid.auto',
    ANTHROPIC_MODEL: 'cc.anthropic/liquid.auto',
    CLAUDE_CODE_ATTRIBUTION_HEADER: '0',
    CLAUDE_CODE_AUTO_MODE_SERVER: '0',
    CLAUDE_CODE_MAX_OUTPUT_TOKENS: '16384',
    CLAUDE_CODE_SUBAGENT_MODEL: 'cc.anthropic/liquid.auto',
  },
  settingSources: [],
  allowedTools: ['Read', 'Glob'],
}

for await (const message of query({ prompt: 'List the files here.', options })) {
  console.log(message)
}

The Claude Code guide explains each variable. These four lines matter for the SDK:

Differences between the two languages:

• In TypeScript, env replaces the subprocess environment. Keep ...process.env first, so the CLI and the commands of the agent keep PATH, HOME and the rest.
• In Python, the SDK adds env to the inherited environment.

setting_sources=[] also stops the CLI from loading CLAUDE.md files, skills and hooks from those settings. To load the settings of one project, pass ["project"]. Then make sure that its .claude/settings.json has no env block.

3. Run it

Save the Python version as agent.py or the TypeScript version as agent.mts. Run it from the shell where LIQUID_API_KEY is set:

python agent.py
# or
npx tsx agent.mts

The example allows only the Read and Glob tools. Change allowed_tools / allowedTools and the prompt for your own agent.

4. Check it works

Each request of the agent is a job on the exchange. Open the Overview or Credits page. The receipt of each job names the client as Claude Agent SDK, with the SDK version, and shows its cap.

total_cost_usd in the result message of the SDK is an estimate from token counts. It is not the charge of the exchange. Read the charge from the receipts.

Choose a model

The exchange lists its models to Claude Code with a cc.anthropic/ prefix. A model published as liquid.auto is cc.anthropic/liquid.auto here. Add [1m] if the live input window of the model is one million tokens or more.

The CLI asks for a different model for each type of work, with one variable for each. The example sets all three to the same model:

• ANTHROPIC_MODEL is the main agent.
• ANTHROPIC_DEFAULT_HAIKU_MODEL is background work such as session titles.
• CLAUDE_CODE_SUBAGENT_MODEL is the model that subagents use.

If a variable is not set, its requests ask for a claude-* model that the exchange does not list, and they fail.

The model option of query() sets only the model of the main agent. To send background work to liquid.auto:economy or to a preset, see A different model per task in the Claude Code guide.

Cap each request

The CLI builds the request body, so the SDK cannot send the exchange object. Send the purchasing rules as headers in ANTHROPIC_CUSTOM_HEADERS. Separate headers with a newline:

"ANTHROPIC_CUSTOM_HEADERS": "x-liquid-cap-usd: 0.50\nx-liquid-policy: economy",

• x-liquid-cap-usd is the maximum charge for one request, in USD. An agent sends many requests for each query(), and each has its own cap.
• If the estimated charge of a request is more than the cap, the exchange refuses the request. It does not make the request smaller.
• If the exchange cannot parse a header, it returns 400 invalid_header.
• liquid.auto has a cap of its own, and the header replaces it.

No header can set models. Presets can set models. See Purchasing rules for each header.

Custom tools

Tools that you define with @tool and create_sdk_mcp_server (Python) or tool() and createSdkMcpServer (TypeScript) run in your own process. The model sees them as usual tool definitions, so they need no exchange setting. See the Agent SDK documentation.

Control the cost

The exchange sets a cap on each request before the first token. To limit the total spend of an agent, give it its own key with a spending limit. When the key reaches the limit, the exchange refuses more requests. See API keys.

Troubleshooting

Next steps

• Claude Code: what each shared variable does.
• Purchasing rules: models, strategy and limits, and presets.
• API keys: set a spending limit on the key the agent uses.
• Prompt caching: how the exchange prices cached input.
• Anthropic SDK: call the Messages API directly.