Use A2Agent with OpenCode CLI

This guide covers OpenCode CLI / TUI only. It includes OpenCode installation, creating or editing opencode.json, adding the provider, configuring the API key, selecting a model, and troubleshooting common connection errors. It does not cover other clients or desktop applications.

Prerequisites

OpenCode CLI is installed. Download it from opencode.ai. On Linux/WSL, use the official installer:

curl -fsSL https://opencode.ai/install | bash

Or install with npm:

npm install -g opencode-ai

You have an A2Agent API key. Register at a2agent.me/register, then create a key in the A2Agent dashboard.
A model ID listed on the A2Agent Models page

A2Agent connection values

Setting	Value
Provider ID	`a2agent`
SDK package	`@ai-sdk/openai-compatible`
Base URL	`https://api.a2agent.me/v1`
API protocol	OpenAI Chat Completions
API key	Your A2Agent API key
Model	An exact model ID currently available in A2Agent

For an OpenAI-compatible /v1/chat/completions endpoint, OpenCode’s provider documentation uses @ai-sdk/openai-compatible with the provider’s options.baseURL setting.

Setup

Go to your project directory

In a terminal, enter the project where you want to use OpenCode:

cd /path/to/your/project

Open or create opencode.json

From the project root, run:

nano opencode.json

If the file does not exist, nano creates it. If it exists, nano opens it for editing.

Paste the A2Agent provider configuration

If this is a new opencode.json, paste the following:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "a2agent": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "A2Agent",
      "options": {
        "baseURL": "https://api.a2agent.me/v1",
        "apiKey": "YOUR_A2AGENT_API_KEY"
      },
      "models": {
        "YOUR_MODEL_ID_1": {
          "name": "A2Agent Model 1"
        },
        "YOUR_MODEL_ID_2": {
          "name": "A2Agent Model 2"
        },
        "YOUR_MODEL_ID_3": {
          "name": "A2Agent Model 3"
        }
      }
    }
  }
}

Replace:

YOUR_A2AGENT_API_KEY with your real A2Agent API key.
YOUR_MODEL_ID_1, YOUR_MODEL_ID_2, and YOUR_MODEL_ID_3 with exact model IDs listed on the A2Agent Models page
A2Agent Model 1 and the other display names if desired.

Then save opencode.json

Start OpenCode CLI

Still in the project directory, run:

opencode

Inside the OpenCode session, enter:

/models

Select a model under a2agent.

Troubleshooting

401 Unauthorized

Check that:

The key came from the A2Agent dashboard.
The key was pasted completely, without leading/trailing spaces or line breaks.
You did not enter a login password, an OpenCode key, or a key from another provider.
If you use an environment variable, A2AGENT_API_KEY exactly matches {env:A2AGENT_API_KEY}.

The provider does not appear in /models

Check:

test -f opencode.json && echo "Configuration file found"
python -m json.tool opencode.json >/dev/null && echo "JSON is valid"

Confirm that:

The top-level field is provider, not providers.
The provider ID is a2agent.
npm is @ai-sdk/openai-compatible.
options.baseURL is https://api.a2agent.me/v1.
models contains at least one model ID.
You start OpenCode from the directory that contains this opencode.json.

404 or endpoint path errors

Use this standard Base URL:

https://api.a2agent.me/v1

For an OpenAI Chat Completions-compatible endpoint, use:

"npm": "@ai-sdk/openai-compatible"

Do not use a Markdown-formatted URL or duplicate /v1 in the address.

Model not found

Copy the current model ID from A2Agent Models, replace the corresponding key under models, restart OpenCode, and run:

/models

Model IDs are examples only. Model availability, limits, and pricing can change; when adding or replacing a model, use the exact ID currently shown in your A2Agent account.

Coding CLI Agents

Desktop & IDE Clients

Chat & GUI Apps

Local Runtimes / Harnesses

Prerequisites

A2Agent connection values

Setup

Troubleshooting

Official references

​Prerequisites

​A2Agent connection values

​Setup

​Troubleshooting

​Official references

Prerequisites

A2Agent connection values

Setup

Troubleshooting

Official references