diff --git a/docs.json b/docs.json index f1b5b6fa..554df52b 100644 --- a/docs.json +++ b/docs.json @@ -546,7 +546,8 @@ "enterprise/integrations/bitbucket-data-center", "enterprise/integrations/jira-data-center", "enterprise/integrations/slack", - "enterprise/integrations/external-llm-gateways" + "enterprise/integrations/external-llm-gateways", + "enterprise/integrations/acp-agents" ] }, { diff --git a/enterprise/integrations/acp-agents.mdx b/enterprise/integrations/acp-agents.mdx new file mode 100644 index 00000000..9c19fca5 --- /dev/null +++ b/enterprise/integrations/acp-agents.mdx @@ -0,0 +1,225 @@ +--- +title: Configuring ACP Agents +description: Set up Claude Code, Codex, and Gemini CLI on OpenHands Enterprise — with a provider subscription, a provider API key, or your own LiteLLM/Bedrock proxy. +icon: robot +--- + +OpenHands Enterprise (OHE) can run your conversations with the built-in +**OpenHands** agent or with a third-party **ACP agent** — Claude Code, Codex, or +Gemini CLI. You choose and configure this on the **Settings → Agent** page. This +guide explains what an ACP agent is, walks through the three ways to give it +model access, and answers the questions we hear most often. + +## OpenHands agent vs. ACP agent + +| | OpenHands agent | ACP agent | +|---|---|---| +| Who runs the loop | OpenHands | The provider's own CLI (Claude Code, Codex, Gemini CLI) | +| Model configuration | OHE's central LLM settings | Configured per agent on **Settings → Agent** | +| Tools & prompts | OpenHands tools and skills | The provider CLI's own tools and behavior | + +An **ACP agent** uses the [Agent Client Protocol](https://agentclientprotocol.com/protocol/overview) +to run a coding-agent CLI as the backend for your conversation. Instead of OHE +calling an LLM directly, it launches the provider's CLI, which manages its own +model calls, tools, and execution. You send messages and see the results in the +same OHE conversation view. + + + **Where does it run?** The ACP agent CLI runs **inside your sandbox**, next to + your workspace — the same place your code and terminal live. It is not a + separate service you have to host. Because it runs in the sandbox, it has + direct access to the workspace files. + + + + **Model routing is per agent.** OHE's central model configuration applies to + the OpenHands agent. Each ACP agent manages its own model routing through the + settings on this page — so you point each one at the model access you want + (subscription, API key, or your proxy). + + +## Before you start + +- The **Settings → Agent** page must show an **Agent** dropdown with an **ACP** + option. If you only see OpenHands settings, ACP is not enabled for your + deployment — ask your administrator to enable it. +- Changes on this page apply to **new conversations**. A conversation keeps the + agent and settings it started with. + +## The Settings → Agent page + +When you set **Agent** to **ACP**, the page shows: + +- **Preset** — Claude Code, Codex, Gemini CLI, or **Custom**. +- **Command** — the command that launches the agent. Picking a preset fills this + in for you; leave it as-is unless you are running a custom server. +- **Model** — pick a suggested model for the provider, or choose **Custom** to + enter your own model ID. +- **Credentials** — API key, optional base URL, and any provider-specific + sign-in fields. Everything here is optional and is saved as a **global secret** + (the same secrets you can manage under **Settings → Secrets**). + +Fill in what you need, then click **Save** once — it saves the agent choice and +the credentials together. + +## Choose how the agent gets model access + +There are three ways to give an ACP agent access to a model. Pick the one that +matches your situation. + + + + Use this when your team has a provider subscription — Claude Pro/Max, a + ChatGPT plan for Codex, or a Google login for Gemini. No LLM API key needed. + + On **Settings → Agent**, choose **Agent = ACP**, pick the **Preset**, pick a + **Model**, and fill in that provider's sign-in credential: + + | Provider | Sign-in field | How to get it | + |---|---|---| + | **Claude Code** | `CLAUDE_CODE_OAUTH_TOKEN` | Run `claude setup-token` in a terminal | + | **Codex** | `CODEX_AUTH_JSON` | Paste the contents of `~/.codex/auth.json` from a ChatGPT‑logged‑in machine | + | **Gemini CLI** | Vertex AI fields (`GOOGLE_APPLICATION_CREDENTIALS_JSON`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`, `GOOGLE_GENAI_USE_VERTEXAI`) | From your Google Cloud project | + + + For the paste-the-file-contents fields (`CODEX_AUTH_JSON` and Gemini's + `GOOGLE_APPLICATION_CREDENTIALS_JSON`), copy the file straight to your + clipboard instead of opening it. On macOS, from a terminal window: + + ```bash + cat ~/.codex/auth.json | pbcopy + ``` + + Then paste into the `CODEX_AUTH_JSON` field. (On Linux, use `xclip + -selection clipboard` or `wl-copy` in place of `pbcopy`.) + + + Leave the API key and base URL blank in this mode. **Save**, then start a new + conversation. + + + + Use this to point the agent straight at Anthropic, OpenAI, or Google with an + API key from that provider. + + On **Settings → Agent**, choose **Agent = ACP**, pick the **Preset**, pick a + **Model**, and set the provider's **API key**. Leave the base URL blank so the + CLI uses the provider's default endpoint. + + | Provider | API key field | + |---|---| + | **Claude Code** | `ANTHROPIC_API_KEY` | + | **Codex** | `OPENAI_API_KEY` | + | **Gemini CLI** | `GEMINI_API_KEY` | + + Leave the subscription/sign-in fields blank in this mode (see + [Which credential wins](#which-credential-wins)). **Save**, then start a new + conversation. + + + + Use this when you already run a LiteLLM proxy (including one that fronts AWS + Bedrock) and want ACP agents to use your managed models — no external + provider API keys required. This is the recommended setup for self-hosted + deployments that already centralize model access. + + On **Settings → Agent**, choose **Agent = ACP**, pick the **Preset**, pick a + **Model**, then set the provider's **API key** to your LiteLLM key and its + **base URL** to your proxy URL: + + | Provider | Set API key to your LiteLLM key | Set base URL to your proxy | + |---|---|---| + | **Claude Code** | `ANTHROPIC_API_KEY` | `ANTHROPIC_BASE_URL` | + | **Codex** | `OPENAI_API_KEY` | `OPENAI_BASE_URL` | + | **Gemini CLI** | `GEMINI_API_KEY` (required) | `GEMINI_BASE_URL` | + + Leave the subscription/sign-in fields blank so they don't override the proxy + (see [Which credential wins](#which-credential-wins)). **Save**, then start a + new conversation. + + + Your proxy URL is your deployment's LiteLLM URL. On OpenHands SaaS this is + `https://llm-proxy.app.all-hands.dev`; on a self-hosted cluster it's your + own LiteLLM endpoint. The model you pick must be registered on your proxy — + see [Why do I get "model not found"](#faq). + + + + +## Which credential wins + +Each provider can authenticate two ways, and its **sign-in credential takes +priority over an API key**. If you set both, the API key and base URL are +ignored — which is the usual reason a proxy or key "does nothing." Set only the +credentials for the mode you want: + +| Provider | Sign-in credential (wins if set) | API key + base URL (used only when sign-in is blank) | +|---|---|---| +| **Claude Code** | `CLAUDE_CODE_OAUTH_TOKEN` | `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL` | +| **Codex** | `CODEX_AUTH_JSON` | `OPENAI_API_KEY`, `OPENAI_BASE_URL` | +| **Gemini CLI** | Vertex/OAuth fields (`GOOGLE_APPLICATION_CREDENTIALS_JSON`, `GOOGLE_CLOUD_*`, `GOOGLE_GENAI_USE_VERTEXAI`) | `GEMINI_API_KEY`, `GEMINI_BASE_URL` | + + + To route through a proxy or a direct API key, leave the sign-in credential for + that provider **blank**. For Claude Code in particular, a + `CLAUDE_CODE_OAUTH_TOKEN` causes both `ANTHROPIC_API_KEY` and + `ANTHROPIC_BASE_URL` to be dropped. + + +## FAQ + + + + No. Point each ACP agent at your proxy using its API key and base URL fields + (the **Your LiteLLM / Bedrock proxy** tab above). The agent then uses your + managed models, and no Anthropic/OpenAI/Google key is required. + + + + No. OHE's central LLM settings apply to the OpenHands agent. Each ACP agent + manages its own model routing through the credentials on the + **Settings → Agent** page. That's why you configure the model access per agent + here. + + + + No — and that's what makes this reliable. Each CLI resolves its own model and + calls your proxy directly in that provider's native format; OHE does not sit + in the middle rewriting the request. The only requirement is on your proxy: + register each model under the name that CLI uses and accept that provider's + API format (LiteLLM supports all three, including with Bedrock upstream). + + + + The model you selected isn't registered on your proxy under the name the CLI + sent. Register that model on the proxy, or pick a model in OHE that your proxy + already exposes. + + + + A sign-in credential is set and taking priority. Clear the provider's sign-in + field (`CLAUDE_CODE_OAUTH_TOKEN`, `CODEX_AUTH_JSON`, or Gemini's Vertex/OAuth + fields), re-save the API key and base URL, and start a new conversation. See + [Which credential wins](#which-credential-wins). + + + + Agent and credential changes apply to **new** conversations. Start a new one + to pick up the change. + + + + ACP is not enabled for your deployment. Ask your administrator to enable it. + + + + Yes. Choose the **Custom** preset and enter the launch command for any + stdio ACP server, then add whatever credentials it expects as secrets. + + + +## Related + +- [ACP Agents](/openhands/usage/agent-canvas/acp-agents) — how ACP agents work and how authentication is detected +- [External LLM Gateways](/enterprise/integrations/external-llm-gateways) — route the **OpenHands** agent through an external gateway +- [Agent Client Protocol](https://agentclientprotocol.com/protocol/overview)