Bring your own AI provider

TL;DR. By default your assistants run on the AI provider Coffield.io manages for you — zero setup, just works. On the Custom plan you can point them at your own OpenAI, Azure OpenAI, Anthropic, Ollama, or vLLM account instead. You pay the provider directly, your conversations stay on the provider you pick, and you can flip back to the Coffield.io default any time. Find it under Integrations → Bring your own AI provider in the dashboard.

#Who is this for?

Most teams should leave this alone — the Coffield.io-managed provider is faster to set up, doesn't require a separate API key to manage, and is included in your plan price. Reach for "bring your own" when one of these is true:

• Data-residency policy. Your legal or compliance team requires the LLM call to run on a specific provider you have a contract with (e.g. Azure OpenAI in a specific Azure region).
• Self-hosted requirement. You want the entire LLM to run on your own infrastructure — typical for healthcare, finance, defence — and you already operate Ollama or vLLM.
• Volume cost optimisation. You have negotiated a better rate with a provider than what comes baked into your plan.
• Specific model preference. You need a model that isn't on Coffield.io's managed list (e.g. an Anthropic Claude variant we don't yet expose, or a fine-tune you host yourself).

If none of those apply, skip this page — the default works.

#What providers are supported?

Coffield.io does not currently support Google Vertex AI, AWS Bedrock, or Cohere as a "bring your own" target. If you need one of those, get in touch — most can be reached via a thin OpenAI-compatible proxy.

#How to set it up

1. Open Integrations → Bring your own AI provider in the dashboard.
2. Pick a preset from the Provider preset dropdown. The form auto-fills sensible defaults for that preset.
3. Paste your API key. (For Ollama / vLLM with no auth, leave it blank.)
4. Adjust the Model name if you want a different model than the suggested default.
5. Click Test connection. Coffield.io sends a one-token "ping" through your config and reports back. If it succeeds you'll see "Connection succeeded — model reported: …". If it fails you'll see a plain-English error — usually it's a typo in the endpoint URL, an expired key, or a model name your provider doesn't recognise.
6. Click Save settings. The change is live immediately — there is no deploy step.

Send a test message from any of your assistants to confirm everything works end-to-end.

#Where do I get an API key?

• OpenAI — sign in at https://platform.openai.com/api-keys, click Create new secret key. Copy it once; OpenAI never shows it again.
• Azure OpenAI — in the Azure portal, open your OpenAI resource, click Keys and Endpoint, copy KEY 1 or KEY 2.
• Anthropic — sign in at https://console.anthropic.com/settings/keys, click Create Key.
• Ollama — no API key. Leave the field blank.
• vLLM — if your server is configured with --api-key YOUR_KEY paste that here; otherwise leave blank.

#How is my API key stored?

Encrypted at rest in the tenants.llm_provider_config column using Laravel's encrypted:array cast. The plaintext key never appears in:

• Application logs
• The audit trail
• The "Active right now" banner at the top of the page
• The form when you reopen the page — the field shows blank and blank means "keep the existing key"

The only place we decrypt and use it is the in-flight LLM request, server-to-server. The visitor's browser never sees it.

#How do I rotate or revoke my key?

To rotate: paste the new key into the API key field and click Save. The old key is overwritten.

To revoke and switch back to Coffield.io default: pick "Use Coffield.io default (managed provider)" from the Provider preset dropdown and click Save. Your llm_provider_config row is set to null and every subsequent assistant reply falls back to the platform-managed provider.

#What about tool / function calling?

Coffield.io assistants don't use the OpenAI / Anthropic tool-calling protocol. Tools (lead capture, booking, order lookup, support escalation, webhook trigger, …) are invoked out-of-band by the embed widget against the dedicated /api/agent/embed/* endpoints. The chat completion is plain text only.

That means any OpenAI-compatible endpoint works, including older models that don't support function calling, and self-hosted servers that only implement chat completions. You don't have to worry about whether your provider supports tools — Coffield.io handles tools server-side regardless of the LLM.

#What happens when I downgrade?

The Custom plan is the entitlement gate. The day you downgrade, LlmProviderEntitlementService::isEntitled() flips to false and LlmProviderService immediately stops reading your override — every assistant reply uses the Coffield.io default again. The llm_provider_config row stays on file (encrypted) so if you ever upgrade back, your settings are still there waiting.

You can't edit the form while downgraded — the page shows a friendly "Upgrade required" banner explaining what tier you need.

#What if my provider is down?

The provider call is wrapped in a try/catch. If your endpoint is unreachable, times out, or returns an HTTP error, the assistant returns the fallback reply configured in AGENT_LLM_FALLBACK_REPLY (default: "Thanks for your message — a teammate will follow up shortly."). The error is logged to the application log with agent_id, tenant_id, and the provider error message — but the visitor never sees a stack trace.

If you want to be alerted when this happens, hook your log driver (Sentry, Bugsnag, Papertrail, …) into the warning channel.

#Troubleshooting

When you click Test connection Coffield.io runs a one-token request through your config and reports back in plain English. Below are the messages you might see and what they mean.

"Connection succeeded — your AI provider is reachable and answered our test request." Everything works. Save settings and send a test message from any assistant to confirm end-to-end.

"Your API key was rejected by the provider. Double-check the key (and any header settings) and try again." Your API key is wrong, expired, or for a different account. Common gotchas:

• Extra whitespace or quote characters when you pasted the key. Re-copy from the provider's dashboard.
• For Azure OpenAI: the form uses the api-key header automatically when you pick the Azure preset. If you picked the generic OpenAI-compatible preset, switch to Azure.
• The key was rotated on the provider side but not updated here.

"The endpoint URL doesn't look right — the provider returned 'Not found'. Verify the base URL and model name against your provider's docs." Usually means the base URL is missing a path segment. For OpenAI the URL must end in /v1. For Azure OpenAI it must include the deployment path: https://YOUR-RESOURCE.openai.azure.com/openai/deployments/YOUR-DEPLOYMENT.

"That URL answered, but the response wasn't in the expected format. Double-check the base URL — it should point to your provider's API root (for example, 'https://api.openai.com/v1'), not a marketing page." You pasted a URL like https://openai.com or https://www.google.com. Coffield.io got HTML back instead of JSON. Use the API base URL, not the marketing site.

"The endpoint answered, but the response format didn't match what we expected. Double-check the base URL points to a chat-completions endpoint and the model name matches one your provider serves." Means we reached the URL, got JSON, but the shape wasn't OpenAI/Anthropic-compatible. Often a typo in the model name (e.g. gpt-4o-min instead of gpt-4o-mini) or pointing at a non-chat endpoint.

"Your provider account is out of credit (or your billing plan is paused). Top up your account on your provider's dashboard, then try again." The provider returned a billing-related HTTP 402 or a insufficient_quota response body. Add a payment method or buy more credit on the provider's dashboard.

"Your provider is rate-limiting these requests right now. Wait a minute and try again." Provider HTTP 429 without a billing signal. Wait, then retry.

"Your provider is having trouble right now (server error). Try again in a few minutes — your settings look fine." Provider HTTP 5xx — it's their side, not yours. Coffield.io's normal fallback reply protects live conversations while you wait.

"The provider rejected the test request. The model name may be wrong, or the endpoint expects a different API format." HTTP 400/422 — usually a model-name typo, or the wrong driver preset (e.g. you picked Anthropic but pasted an Azure URL).

"The request timed out before the provider answered. The endpoint may be slow or unreachable from our servers." Slow self-hosted server, or a firewall is silently dropping our connection. Confirm the endpoint responds within ~15 seconds from a public test server (e.g. curl -m 15 ...).

"We couldn't resolve the endpoint hostname. Double-check the base URL for typos." DNS lookup failed. Typo in the hostname, or the host is on a private internal DNS our servers can't see. Use a public DNS name or a public IP.

"We couldn't connect to the endpoint URL. Make sure the host is reachable from our servers and accepting requests on that port." Hostname resolves but the connection was refused / reset. Check that the service is running and that any firewall / security group allows traffic from Coffield.io's egress IPs on the configured port.

"The endpoint's SSL certificate could not be verified. If you're testing a private endpoint, check that its certificate is valid and trusted." Self-signed or expired certificate. Use a real public cert (Let's Encrypt is free) on any internet-reachable endpoint.

"Paste your API key in the box above (or click reveal to confirm the existing one) before testing." / "Add the endpoint URL above before testing — we need to know where to send the request." / "Pick a model name above before testing — for example 'gpt-4o-mini' for OpenAI." You clicked Test connection before filling all three required fields. Fill them in (or click the reveal eye to confirm the key you already saved is still in place) and try again.

The page says "Active right now: Coffield.io default" even though I saved a config You may have been downgraded from Custom. Check Subscriptions — if you're not on Custom the override is intentionally ignored regardless of what's saved.

#Related

• Security and data handling — what's encrypted, how tenant isolation works, what visitors never see.
• External integrations — MCP bearer tokens, webhooks, REST API.
• Engineering reference: docs/agent-system/PHASE_3_DECISIONS.md §6 documents why this is intentionally Custom-only and why tool calling stays out-of-band.