Koko (AI Assistant)

What users see (by design)

Koko is built to be production-safe:

• If no AI provider is configured, Koko stays available in safe fallback mode (fast, deterministic navigation help).
• If an upstream AI provider fails, Koko automatically degrades to safe mode so the UI never gets blocked.
• Provider/config diagnostics are intentionally hidden from end users unless you explicitly enable operator diagnostics.

Step-by-step: enable full AI responses

1. Pick a provider (OpenAI, Anthropic, Gemini, xAI, DeepSeek, or Ollama).
2. Enable the feature flag:
   • Set NEXT_PUBLIC_FEATURE_AI_AGENTS=true.
3. Configure at least one provider key:
   • OpenAI: OPENAI_API_KEY (optional OPENAI_MODEL)
   • Anthropic: ANTHROPIC_API_KEY (optional ANTHROPIC_MODEL)
   • Gemini: GEMINI_API_KEY (optional GEMINI_MODEL)
   • xAI: XAI_API_KEY (optional XAI_MODEL)
   • DeepSeek: DEEPSEEK_API_KEY (optional DEEPSEEK_MODEL)
   • Ollama: OLLAMA_BASE_URL (optional OLLAMA_MODEL)
4. Choose routing mode (optional):
   • KOKO_CHAT_MODE=fallback (default): try providers in order until one succeeds.
   • KOKO_CHAT_MODE=single: use the first configured provider (or a forced provider).
   • KOKO_CHAT_MODE=ensemble: query multiple providers and synthesize (higher cost).
   • Provider order: KOKO_PROVIDER_ORDER=openai,anthropic,google,xai,deepseek,ollama
5. Decide on anonymous access:
   • By default, when a provider is configured Koko requires auth (cost/abuse control).
   • Set KOKO_ALLOW_ANON=true only if you intentionally want anonymous AI access.

Operator diagnostics (optional)

For troubleshooting only, you can enable operator diagnostics (do not enable by default in production):

• KOKO_EXPOSE_DIAGNOSTICS=true
• Optionally enable agent tools (web fetch) with KOKO_AGENT_TOOLS=true.

Where Koko lives

• Chat endpoint: /api/agents/chat
• In-app experience: /app/koko
• Site widget: the floating Koko button (where enabled)

Related

• Documentation home
• API reference