content/providers/03-community-providers/03-acp.mdx
ACP (Agent Client Protocol) is an open protocol that enables seamless communication between AI agents and client applications.
The ACP provider bridges ACP agents (like Claude Code, Gemini CLI, Codex CLI, and many more) to the AI SDK by communicating with them via the Agent Client Protocol and exposing them through the LanguageModel interface, enabling you to build web applications and Node.js services with ACP agents.
Learn more about ACP in the Agent Client Protocol Documentation.
The ACP provider is available in the @mcpc-tech/acp-ai-provider module. You can install it with:
<Tabs items={['pnpm', 'npm', 'yarn', 'bun']}> <Tab> <Snippet text="pnpm add @mcpc-tech/acp-ai-provider" dark /> </Tab> <Tab> <Snippet text="npm install @mcpc-tech/acp-ai-provider" dark /> </Tab> <Tab> <Snippet text="yarn add @mcpc-tech/acp-ai-provider" dark /> </Tab> <Tab> <Snippet text="bun add @mcpc-tech/acp-ai-provider" dark /> </Tab> </Tabs>
To create an ACP provider instance, use the createACPProvider function:
import { createACPProvider } from '@mcpc-tech/acp-ai-provider';
const provider = createACPProvider({
command: 'gemini',
args: ['--experimental-acp'],
session: {
cwd: process.cwd(),
mcpServers: [],
},
});
The provider accepts the following configuration:
command string (required)
The command to execute the ACP agent (e.g., 'gemini', 'claude-code-acp', 'codex-acp').
args string[] (optional)
Arguments to pass to the command (e.g., ['--experimental-acp']).
env Record<string, string> (optional)
Environment variables for the agent process.
session ACPSessionConfig (required)
Session configuration including:
cwd: Working directory for the agentmcpServers: Array of MCP server configurations to provide tools to the agentauthMethodId string (optional)
Authentication method ID to use if required by the ACP agent.
The ACP provider exposes a single language model that represents the configured ACP agent:
const model = provider.languageModel();
Note: Currently, you cannot select a specific model. See Limitations for more details.
import { createACPProvider } from '@mcpc-tech/acp-ai-provider';
import { generateText } from 'ai';
const provider = createACPProvider({
command: 'gemini',
args: ['--experimental-acp'],
session: {
cwd: process.cwd(),
mcpServers: [],
},
});
const { text } = await generateText({
model: provider.languageModel(),
prompt: 'What is the Agent Client Protocol?',
});
console.log(text);
import { createACPProvider } from '@mcpc-tech/acp-ai-provider';
import { streamText } from 'ai';
const provider = createACPProvider({
command: 'claude-code-acp',
session: {
cwd: process.cwd(),
mcpServers: [],
},
});
const { textStream } = streamText({
model: provider.languageModel(),
prompt: 'Write a simple Hello World program',
});
for await (const chunk of textStream) {
process.stdout.write(chunk);
}
Tools are provided to ACP agents through MCP (Model Context Protocol) servers, not through the AI SDK's tools parameter:
import { createACPProvider } from '@mcpc-tech/acp-ai-provider';
import { generateText } from 'ai';
const provider = createACPProvider({
command: 'gemini',
args: ['--experimental-acp'],
session: {
cwd: process.cwd(),
mcpServers: [
{
type: 'stdio',
name: 'filesystem',
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
},
],
},
});
const result = await generateText({
model: provider.languageModel(),
prompt: 'List files in /tmp',
});
The ACP provider handles tool execution through provider-defined tools. Tools are called and executed by the ACP agent, and results are reported back through the AI SDK's streaming interface.
To stream tool calls, pass the provider tools to the AI SDK:
const result = await generateText({
model: provider.languageModel(),
prompt: 'List files in /tmp',
tools: provider.tools,
});
Tool calls follow this structure:
{
toolCallId: string; // Unique ID of the tool call
toolName: string; // Name of the tool being called
args: Record<string, unknown>; // Input arguments
}
The ACP provider works with various ACP-compatible agents:
command: 'gemini' with args: ['--experimental-acp']command: 'claude-code-acp'command: 'codex-acp'Some agents require authentication. Specify the auth method ID:
const provider = createACPProvider({
command: 'gemini',
args: ['--experimental-acp'],
authMethodId: 'gemini-api-key',
session: {
cwd: process.cwd(),
mcpServers: [],
},
});
Pass environment variables to the agent process:
const provider = createACPProvider({
command: 'gemini',
args: ['--experimental-acp'],
env: {
GEMINI_API_KEY: process.env.GEMINI_API_KEY,
DEBUG: 'true',
},
session: {
cwd: process.cwd(),
mcpServers: [],
},
});
tools parameter