Agent Providers
Agent providers are the AI coding assistants that execute session tasks. Polygent is provider-agnostic — you can switch providers per workspace, per session, or per workflow without re-tooling.
Supported Providers
Polygent supports seven providers out of the box. You only need to install and configure the ones your team plans to use.
| Provider | CLI Reference |
|---|---|
| Claude Code | https://docs.claude.com/en/docs/claude-code/overview |
| Gemini CLI | https://github.com/google-gemini/gemini-cli |
| OpenCode | https://opencode.ai |
| Kilo CLI | https://kilocode.ai |
| Codex | https://github.com/openai/codex |
| Qwen Code | https://github.com/QwenLM/qwen-code |
| Polygent Code | Built-in agent — no external CLI. Connects directly to your chosen model backend using your own API key. |
Most providers shell out to a CLI installed on the API (or Agent) host. Polygent Code is different — it runs in-process, so no third-party CLI install is needed. Credentials for any provider are supplied via environment variables — Polygent never stores raw API keys.
Feature Comparison
The matrix below reflects what each provider's CLI surfaces to Polygent today. Empty cells mean the upstream CLI does not expose the capability — Polygent works around the gap where possible but cannot create signal that the CLI never emits.
| Feature | Claude Code | Gemini CLI | OpenCode | Kilo CLI | Codex | Qwen Code | Polygent Code |
|---|---|---|---|---|---|---|---|
| Thinking / reasoning trace | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Token usage (input / output / cache) | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| MCP server injection (Polygent built-in MCP) | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| File attachments (images, docs) | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Built-in tools — Read / Edit / Write | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Built-in tools — Bash / shell | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Built-in tools — Glob / Grep | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Built-in tools — WebFetch | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Built-in tools — WebSearch | Yes | Yes | Yes | Yes | Yes | Yes | — |
| Built-in tools — Sub-agent / Task | Yes | Yes | — | — | Yes | Yes | Yes |
| Built-in tools — TodoWrite (progress tracking) | Yes | — | Yes | Yes | Yes | Yes | Yes |
| Cost audit | Yes | — | Yes | Yes | — | Yes | Yes |
| Change system prompt | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Budget per task (USD) | Yes | — | — | — | — | — | Yes |
| Per-mode tool allowlist (Chat / Bot / Develop) | Yes | — | — | — | — | Yes | Yes |
Notes on the cost row
When a CLI does not emit total_cost_usd (Gemini CLI, Codex), Polygent still records token counts on every audit row, but cannot calculate the final cost of the session. In this case, the cost is $0.
Notes on the budget-per-task row
Only Claude Code and Polygent Code accept a USD cap that stops the agent mid-run before it overspends. For all other providers the CLI exposes no native cost limit, so Polygent enforces budgets after each run by inspecting audit rows — it cannot interrupt an in-flight turn.
Where to Configure
All provider configuration lives in Settings → Providers (persisted in the database, takes effect immediately — no API restart required). Per provider, the UI exposes:
| Setting | Purpose |
|---|---|
| Provider Status | Enable or disable the provider. Disabled providers are hidden from selection |
| Model Visibility Toggle | Hide unwanted models from selection dropdowns workspace-wide |
| Custom Models | Add or remove model identifiers beyond the built-in list |
Changes apply to every workspace that uses the provider.
Defaults: Only Claude Code and Polygent Code are enabled out of the box. All other providers (Gemini CLI, OpenCode, Kilo CLI, Codex, Qwen Code) are disabled by default and must be explicitly enabled before users can select them.
Provider Status (Enable / Disable)
Toggle a provider off to remove it from every selection dropdown across the application — session creation, bot configuration, workflow steps, ticket configuration, and global settings (Insights, Merge Conflicts, Code Review, Verification).
Disabling a provider does not affect existing sessions, bots, automations, or workflows already configured with that provider — they continue to function normally. Only new selections are filtered. To re-enable a provider, toggle it back on; selection dropdowns refresh automatically after saving settings.
Permissions: access to provider configuration requires
settings.viewandsettings.manage(admins always have access).
Model Visibility
Each provider ships with a default list of supported models. Toggle individual models off to hide them from the model dropdowns shown to users when starting sessions, configuring tickets, or running workflows. Hidden models stay configured for any existing references; only new selections are filtered.
Custom Models
If a provider exposes a model that isn't in Polygent's built-in list (e.g., a new release, a regional alias, or an internal proxy), add it under Custom Models:
- Open Settings → Providers → {Provider}
- Add the model identifier exactly as the CLI accepts it
- The model appears in selection dropdowns immediately
Remove custom models the same way. Removing a model in active use leaves running sessions untouched but prevents new selections.
Where Providers Are Selected
Once a provider and model are configured, users select them at:
| Place | Purpose |
|---|---|
| Workspace defaults | Default provider/model for the whole workspace |
| Session start | Override per session at creation time |
| Ticket configuration | Per-ticket provider/model for the implementation step |
| Workflow steps | Override per Message / Ralph Loop step |
| Bot configuration | Bots are pinned to one provider/model |
| Automation | Per-automation override |
| Insights (global setting) | Provider/model used to extract insights |
| Merge Conflicts (global setting) | Provider/model used for AI-assisted conflict resolution |
Credentials
Each provider CLI reads its own environment variables for authentication (e.g., ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY). Set these in the service account's environment on each host that runs sessions, or per-workspace under Environment Variables.
Polygent never logs credential values.
Polygent Code: model selection and credentials
Polygent Code connects directly to the model backend implied by the model you pick in the dropdown, using your own API key. Set the matching credential as an environment variable (per-host or per-workspace) for each backend your team selects:
| Backend | Required env var |
|---|---|
| Anthropic | ANTHROPIC_API_KEY |
| OpenAI | OPENAI_API_KEY |
| Google Gemini | GEMINI_API_KEY |
| OpenRouter | OPENROUTER_API_KEY |
| OpenCode Zen | ZEN_API_KEY (optional) |
| Kilo Gateway | KILO_API_KEY (optional) |
You can switch backends between turns in a single session by changing the selected model.
Free models (no account needed)
The dropdown includes free models routed through curated gateways that require no signup. Models prefixed "Kilo …" (e.g. Kilo Auto Free) use the Kilo Gateway, and the "(free)" entries such as DeepSeek V4 Flash (free) use OpenCode Zen. These work without setting KILO_API_KEY / ZEN_API_KEY — leave the env var unset and the request goes out unauthenticated. Setting the key is optional (e.g. to lift free-tier rate limits). Free models are subject to upstream rate limits; a transient "model at capacity" error just means you should retry or pick another free model.
Distributed Hosts
When sessions are dispatched to a Session Agent on a separate machine, the same provider CLI must be installed on that host with the same credentials and model availability.
Troubleshooting
| Symptom | Likely Cause |
|---|---|
| CLI works in your shell but fails as a service | Service runs under a different user — set credentials in the service's environment |
| Model not in dropdown | Hidden via Model Visibility, or not in Custom Models — add it |
| Sessions hang at start | Provider needs interactive login — log in once as the service account, or use API-key auth |
| Different version on different hosts | Upgrade each host independently; Polygent does not push CLI binaries |