When to Use
- Adding a new LLM provider (OpenAI-compatible or otherwise) the agent can use.
For a non-LLM external API tool, use agentic-tool-integration.
Critical Rules
- NEVER let a provider API key reach a scan container. Keys live in exactly
two places: Postgres
user_llm_providersrows and, in transit, on the wire between webapp and agent. The recon / scan / MCP containers must never see them. Do not thread a provider key through recon settings or container env. - NEVER add a model id that is not prefix-routed. Anything other than
claude-*and bare OpenAI ids MUST carry aprovider/<model>prefix, resolved byparse_model_provider()at agentic/orchestrator_helpers/llm_setup.py:67. An unprefixed id routes to the wrong provider silently. - ALWAYS register the provider in the webapp provider-type registry and propagate the key kwarg into every LLM call site. A provider registered but not propagated builds a client with no credentials. The guide enumerates all 11 integration points; touch each.
The two invariants
| Invariant | Where | Failure if broken |
|---|---|---|
| Keys only in Postgres + webapp<->agent transit | webapp/prisma/schema.prisma user_llm_providers; agent settings fetch | key leaks into scan/MCP containers |
| Model id prefix routing | parse_model_provider() llm_setup.py:67 | model routes to the wrong provider |
Commands
bashdocker compose build agent && docker compose up -d agent # agentic/ is baked docker compose exec webapp npx prisma db push # provider schema changes (NEVER prisma migrate)
Resources
- docs/readmes/coding_agent_prompts/PROVIDER_INTEGRATION_GUIDELINES.md - the 11 integration points, decision tree, and model-id prefix table
- Related skill:
agentic-tool-integration

