Anthropic

Why

Setup

1. Confirm apps/backend/package.json includes "tooling-ai-anthropic": "workspace:*" (default in the boilerplate).
2. Run make deps-install if you changed dependencies.
3. Add or extend tools.ai in apps/backend/src/configuration/development.ts (and production.ts when ready):

ai: {
  request: {
    timeoutMs: 60_000,
    maxAttempts: 3,
    retryDelayMs: 500,
    totalTimeoutMs: 180_000,
  },
  anthropic: {
    apiKey: process.env.ANTHROPIC_API_KEY,
    models: ['claude-sonnet-4-20250514'],
    defaultModel: 'claude-sonnet-4-20250514',
  },
},

4. No compose.yml changes are required — Anthropic is reached over HTTPS; no extra Docker service.
5. Add to .env.development:

ANTHROPIC_API_KEY=sk-ant-...

6. Verify:

make test module=tooling-ai-anthropic
make test module=backend path=apps/backend/src/tools/ai/__tests__/instrumentation.spec.ts

Local observability

Adding a new model id

1. Add the model string to tools.ai.anthropic.models in each environment config that uses Anthropic.
2. Optionally set defaultModel to that id (must remain in models).
3. Confirm getAvailableModels returns the new id before exposing it in UI.
4. Run make test module=tooling-ai-anthropic.

Gotchas

• Model ids must match Anthropic’s API names exactly — typos throw AiValidationError at the loader, not a clear SDK message.
• If Anthropic is the only provider configured, omitting params.model uses defaultModel or the first models entry.
• Loader provider order is anthropic → openai → google; Anthropic is primary only when it is the first block present in config and loaded.

What’s next?

• AI tooling overview — routing, request policy, and tools.ai usage
• OpenAI · Google Gemini — sibling providers
• Configuration — env vars and config files
• Tooling system — pluggable tool architecture