Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(llm): serve Anthropic SDK clients at an agent-scoped base URL and keep block-array system prompts intact on Anthropic lanes

nirholas53687d994925
diff --git a/api/llm/anthropic.js b/api/llm/anthropic.js
index f81c03d73..d13e5427b 100644
--- a/api/llm/anthropic.js
+++ b/api/llm/anthropic.js
@@ -436,10 +436,9 @@ const systemSchema = z.union([
]);
/**
- * Collapse a block-array `system` to the plain string every lane below reads.
- * The OpenAI-shape lanes need a string, and the Anthropic lanes get one cache
- * breakpoint back from sanitizeAnthropicBody on a long prompt, so nothing a
- * caller's block markers bought is lost.
+ * Collapse a block-array `system` to the plain string an OpenAI-shape lane
+ * reads. The Anthropic and Vertex lanes receive the caller's blocks unchanged,
+ * cache_control markers included.
*/
export function flattenSystem(system) {
if (!Array.isArray(system)) return system;
@@ -578,7 +577,6 @@ export default wrap(async (req, res) => {
const rawBody = await readJson(req);
const body = parse(bodySchema, rawBody);
- if (body.system !== undefined) body.system = flattenSystem(body.system);
const requestedModel = resolveRequestedModel(body.model, policy.brain?.model);
// Ordered fallback chain for 429 / 5xx from OpenRouter free tier:
@@ -1057,7 +1055,8 @@ export function toolResultText(content) {
export function anthropicBodyToOpenAI(body, { provider } = {}) {
const messages = [];
- if (body.system) messages.push({ role: 'system', content: body.system });
+ const system = flattenSystem(body.system);
+ if (system) messages.push({ role: 'system', content: system });
for (const m of body.messages) {
if (typeof m.content === 'string') {
diff --git a/api/llm/anthropic/agents/[agent]/v1/messages.js b/api/llm/anthropic/agents/[agent]/v1/messages.js
new file mode 100644
index 000000000..8841b3a0c
--- /dev/null
+++ b/api/llm/anthropic/agents/[agent]/v1/messages.js
@@ -0,0 +1,15 @@
+// POST /api/llm/anthropic/agents/:agent/v1/messages
+//
+// The we-pay proxy (api/llm/anthropic.js) at the path an Anthropic SDK client
+// builds for itself. Every official SDK, and every CLI built on one, takes a
+// base URL and appends `/v1/messages`, with no way to add a query parameter:
+// the agent this call meters against therefore travels in the path instead.
+// A client configured with
+//
+// ANTHROPIC_BASE_URL=https://three.ws/api/llm/anthropic/agents/<agent-id>
+//
+// lands here, and the filesystem route binds `<agent-id>` to req.query.agent,
+// which the proxy reads exactly like its own `?agent=` parameter. Everything
+// else (auth, embed policy, rate limits, quota, the free-model chain) is the
+// one implementation, so the two paths cannot drift.
+export { default } from '../../../../anthropic.js';
diff --git a/data/changelog.json b/data/changelog.json
index 4738273c8..86bcf9960 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,13 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-09-18",
+ "title": "Standard Anthropic SDK clients can now use a three.ws agent's AI budget",
+ "summary": "The AI proxy behind every embedded three.ws agent now answers at the address an Anthropic SDK or command-line tool builds for itself. Point a client at /api/llm/anthropic/agents/<your agent id> with one of your API keys and it runs on that agent's model, limits, and monthly budget. The proxy also stopped turning such clients away over their defaults: a system prompt sent as a list of text blocks is accepted, and an output limit above 16,000 tokens is lowered to 16,000 instead of rejected.",
+ "tags": ["feature", "sdk"],
+ "link": "/docs/api-reference"
+ },
{
"date": "2026-09-18",
"title": "The embedded 3D agent is readable on light websites and quiet in the console",
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 234fe34a3..f4834e988 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -1179,6 +1179,15 @@ POST /api/llm/anthropic?agent=<agent_id>
Older single-provider proxy. Request/response shape matches the [Anthropic Messages API](https://docs.anthropic.com/en/api/messages) exactly. New integrations should use `/api/brain/chat` instead — it supports more providers and emits richer events.
+**Anthropic SDK clients.** An official Anthropic SDK, or a CLI built on one, takes a base URL and appends `/v1/messages` itself, so it cannot add the `agent` query parameter. Point it at the agent-scoped base URL instead, and authenticate with a bearer API key owned by the agent's owner:
+
+```
+ANTHROPIC_BASE_URL=https://three.ws/api/llm/anthropic/agents/<agent_id>
+ANTHROPIC_AUTH_TOKEN=sk_live_...
+```
+
+That reaches `POST /api/llm/anthropic/agents/<agent_id>/v1/messages`, which is this same proxy with the same auth, policy, ceilings and model rules. `system` may be a string or an array of text blocks (at most 64,000 characters in total), and a `max_tokens` above 16,000 is clamped to 16,000 rather than rejected. Only meter against an agent you own: the per-agent ceilings and budget below are that agent's.
+
**Who may call it.** This lane is billed to the platform's own provider keys, so it is scoped to the browser embed it exists for:
| Caller | Result |
diff --git a/tests/api/llm-anthropic.test.js b/tests/api/llm-anthropic.test.js
index 3fc4d91be..76b951f88 100644
--- a/tests/api/llm-anthropic.test.js
+++ b/tests/api/llm-anthropic.test.js
@@ -1068,3 +1068,140 @@ describe('/api/llm/anthropic: streaming, Anthropic lane', () => {
});
});
});
+
+// ── Anthropic SDK clients (base-URL path, block system, large max_tokens) ──
+//
+// An SDK client is configured with a base URL and appends /v1/messages to it,
+// so the agent travels in the path. These pin that such a client, sending what
+// the official SDKs send by default, is served rather than turned away on a
+// field it does not choose.
+
+describe('/api/llm/anthropic: Anthropic SDK clients', () => {
+ const SDK_URL = '/api/llm/anthropic/agents/agent-1/v1/messages?beta=true';
+
+ beforeEach(() => {
+ process.env.OPENROUTER_API_KEY = 'sk-or-test';
+ authState.user = { id: 'platform-user', source: 'bearer' };
+ fetchState.response = () =>
+ upstreamOk({
+ id: 'gen-sdk',
+ choices: [{ message: { role: 'assistant', content: 'ok' }, finish_reason: 'stop' }],
+ usage: { prompt_tokens: 3, completion_tokens: 1 },
+ });
+ });
+
+ async function invokeSdk(body, { query = { agent: 'agent-1' } } = {}) {
+ const req = makeReq({ url: SDK_URL, body, noOrigin: true, headers: { authorization: 'Bearer sk_live_test' } });
+ req.query = query;
+ const res = makeRes();
+ await handler(req, res);
+ return { status: res.statusCode, body: res.body ? safeJson(res.body) : null };
+ }
+
+ it('meters against the agent the router bound from the path segment', async () => {
+ const { status } = await invokeSdk({ ...VALID_BODY, model: 'google/gemma-4-31b-it:free' });
+ expect(status).toBe(200);
+ expect(usageEvents[0]).toMatchObject({ agentId: 'agent-1', status: 'ok' });
+ });
+
+ it('still requires an agent when neither the query nor the path names one', async () => {
+ const { status, body } = await invokeSdk(VALID_BODY, { query: {} });
+ expect(status).toBe(400);
+ expect(body.error).toBe('validation_error');
+ });
+
+ it('still refuses a header-less caller that does not authenticate', async () => {
+ authState.user = null;
+ const { status, body } = await invokeSdk(VALID_BODY);
+ expect(status).toBe(403);
+ expect(body.error).toBe('embed_denied_origin');
+ });
+
+ it('accepts a block-array system prompt and hands OpenAI-shape lanes one string', async () => {
+ const { status } = await invokeSdk({
+ ...VALID_BODY,
+ model: 'google/gemma-4-31b-it:free',
+ system: [
+ { type: 'text', text: 'first block' },
+ { type: 'text', text: 'second block', cache_control: { type: 'ephemeral' } },
+ ],
+ });
+ expect(status).toBe(200);
+ const sent = JSON.parse(fetchState.calls[0].init.body);
+ expect(sent.messages[0]).toEqual({ role: 'system', content: 'first block\n\nsecond block' });
+ });
+
+ it('passes a block-array system prompt to an Anthropic lane unchanged', async () => {
+ const system = [{ type: 'text', text: 'keep my cache marker', cache_control: { type: 'ephemeral' } }];
+ fetchState.response = () => upstreamOk({ ok: true, usage: { input_tokens: 1, output_tokens: 1 } });
+ const { status } = await invokeSdk({ ...VALID_BODY, system });
+ expect(status).toBe(200);
+ expect(fetchState.calls[0].url).toBe('https://api.anthropic.com/v1/messages');
+ expect(JSON.parse(fetchState.calls[0].init.body).system).toEqual(system);
+ });
+
+ it('bounds a block-array system prompt by the same total length as a string one', async () => {
+ const { status, body } = await invokeSdk({
+ ...VALID_BODY,
+ system: [
+ { type: 'text', text: 'a'.repeat(40_000) },
+ { type: 'text', text: 'b'.repeat(40_000) },
+ ],
+ });
+ expect(status).toBe(400);
+ expect(body.error).toBe('validation_error');
+ expect(fetchState.calls).toHaveLength(0);
+ });
+
+ it('clamps an oversized max_tokens instead of rejecting the request', async () => {
+ const { status } = await invokeSdk({ ...VALID_BODY, model: 'google/gemma-4-31b-it:free', max_tokens: 32_000 });
+ expect(status).toBe(200);
+ const sent = JSON.parse(fetchState.calls[0].init.body);
+ expect(sent.max_tokens).toBe(16_000);
+ });
+
+ it('hands a text-block tool_result to an OpenAI-shape model as plain text', async () => {
+ await invokeSdk({
+ ...VALID_BODY,
+ model: 'google/gemma-4-31b-it:free',
+ messages: [
+ { role: 'user', content: 'run it' },
+ { role: 'assistant', content: [{ type: 'tool_use', id: 'toolu_1', name: 'Bash', input: { command: 'ls' } }] },
+ {
+ role: 'user',
+ content: [
+ {
+ type: 'tool_result',
+ tool_use_id: 'toolu_1',
+ content: [
+ { type: 'text', text: 'a.txt' },
+ { type: 'text', text: 'b.txt' },
+ ],
+ },
+ ],
+ },
+ ],
+ });
+ const sent = JSON.parse(fetchState.calls[0].init.body);
+ expect(sent.messages.find((m) => m.role === 'tool')).toEqual({
+ role: 'tool',
+ tool_call_id: 'toolu_1',
+ content: 'a.txt\nb.txt',
+ });
+ });
+});
+
+describe('/api/llm/anthropic: SDK base-URL route', () => {
+ it('resolves the SDK path to the proxy alias and binds the agent segment', async () => {
+ const path = await import('node:path');
+ const { resolveApiHandler } = await import('../../server/route-resolve.mjs');
+ const apiRoot = path.resolve('api');
+ const sdk = resolveApiHandler(apiRoot, '/api/llm/anthropic/agents/4c0e4d18-0544-4c95-a0db-a16896b029be/v1/messages');
+ expect(sdk.file).toBe(path.join(apiRoot, 'llm/anthropic/agents/[agent]/v1/messages.js'));
+ expect(sdk.params).toEqual({ agent: '4c0e4d18-0544-4c95-a0db-a16896b029be' });
+ const alias = await import('../../api/llm/anthropic/agents/[agent]/v1/messages.js');
+ expect(alias.default).toBe(handler);
+ // The canonical path still reaches the proxy file itself.
+ expect(resolveApiHandler(apiRoot, '/api/llm/anthropic').file).toBe(path.join(apiRoot, 'llm/anthropic.js'));
+ });
+});