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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.jsindex 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.jsnew file mode 100644index 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.jsonindex 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.mdindex 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.jsindex 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'));+ });+});