ACP

ACP (Agent Client Protocol)

ACP (Agent Client Protocol)는 AI 에이전트와 클라이언트 애플리케이션 사이의 원활한 통신을 가능하게 하는 오픈 프로토콜이에요.

ACP 프로바이더는 ACP 에이전트(Claude Code, Gemini CLI, Codex CLI 등 더 많은)를 Agent Client Protocol로 통신하고 LanguageModel 인터페이스로 노출해 AI SDK와 연결해요. 이를 통해 ACP 에이전트로 웹 애플리케이션과 Node.js 서비스를 구축할 수 있어요.

출처: 문서

본문

주요 기능 (Key Features)

  • 다중 에이전트 지원: Claude Code, Gemini CLI, Codex CLI 및 기타 ACP 호환 에이전트와 동작해요
  • MCP 서버 통합: MCP(Model Context Protocol) 서버를 연결해 에이전트 기능을 강화할 수 있어요
  • 툴 실행: 에이전트가 AI SDK 인터페이스를 통해 툴을 실행하고 결과를 보고할 수 있어요
  • 프로세스 관리: 에이전트 프로세스의 자동 생성 및 수명주기 관리

ACP에 대해 자세히 알아보려면 Agent Client Protocol 문서를 참고하세요.

설정 (Setup)

ACP 프로바이더는 @mcpc-tech/acp-ai-provider 모듈에서 사용할 수 있어요. 다음과 같이 설치할 수 있어요:

프로바이더 인스턴스 (Provider Instance)

ACP 프로바이더 인스턴스를 만들려면 createACPProvider 함수를 사용하세요:

import { createACPProvider } from '@mcpc-tech/acp-ai-provider';

const provider = createACPProvider({
  command: 'gemini',
  args: ['--experimental-acp'],
  session: {
    cwd: process.cwd(),
    mcpServers: [],
  },
});

구성 옵션 (Configuration Options)

프로바이더는 다음 구성을 받아요:

  • command string (필수)

    ACP 에이전트를 실행할 명령이에요 (예: 'gemini', 'claude-code-acp', 'codex-acp').

  • args string[] (선택)

    명령에 전달할 인자예요 (예: ['--experimental-acp']).

  • env Record<string, string> (선택)

    에이전트 프로세스를 위한 환경 변수예요.

  • session ACPSessionConfig (필수)

    다음을 포함한 세션 구성:

    • cwd: 에이전트의 작업 디렉터리
    • mcpServers: 에이전트에 툴을 제공할 MCP 서버 구성 배열

  • authMethodId string (선택)

    ACP 에이전트가 요구하면 사용할 인증 방법 ID예요.

언어 모델 (Language Models)

ACP 프로바이더는 구성된 ACP 에이전트를 나타내는 단일 언어 모델을 노출해요:

const model = provider.languageModel();

참고: 현재 특정 모델을 선택할 수 없어요. 자세한 내용은 제한 사항을 참고하세요.

예시 (Examples)

텍스트 생성 (Text Generation)

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);

스트리밍 텍스트 (Streaming 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);
}

MCP 서버와 함께 사용 (Tools)

툴은 AI SDK의 tools 파라미터가 아니라 MCP(Model Context Protocol) 서버를 통해 ACP 에이전트에 제공돼요:

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',
});

툴 작업 (Working with Tools)

ACP 프로바이더는 프로바이더 정의 툴을 통해 툴 실행을 처리해요. 툴은 ACP 에이전트가 호출하고 실행하며, 결과는 AI SDK의 스트리밍 인터페이스를 통해 보고돼요.

툴 호출을 스트리밍하려면 프로바이더 툴을 AI SDK에 전달하세요:

const result = await generateText({
  model: provider.languageModel(),
  prompt: 'List files in /tmp',
  tools: provider.tools,
});

툴 호출은 다음 구조를 따릅니다:

{
  toolCallId: string; // Unique ID of the tool call
  toolName: string; // Name of the tool being called
  args: Record<string, unknown>; // Input arguments
}

고급 기능 (Advanced Features)

다중 에이전트 지원 (Multiple Agent Support)

ACP 프로바이더는 다양한 ACP 호환 에이전트와 동작해요:

  • Gemini CLI: command: 'gemini'를 args: ['--experimental-acp']로 사용
  • Claude Code: command: 'claude-code-acp' 사용
  • Codex CLI: command: 'codex-acp' 사용
  • 그리고 더 많은...: 지원되는 에이전트 전체 목록은 공식 ACP 에이전트 페이지 참고

커스텀 인증 (Custom Authentication)

일부 에이전트는 인증이 필요해요. auth 메서드 ID를 지정하세요:

const provider = createACPProvider({
  command: 'gemini',
  args: ['--experimental-acp'],
  authMethodId: 'gemini-api-key',
  session: {
    cwd: process.cwd(),
    mcpServers: [],
  },
});

프로세스 환경 변수 (Process Environment Variables)

에이전트 프로세스에 환경 변수를 전달해요:

const provider = createACPProvider({
  command: 'gemini',
  args: ['--experimental-acp'],
  env: {
    GEMINI_API_KEY: process.env.GEMINI_API_KEY,
    DEBUG: 'true',
  },
  session: {
    cwd: process.cwd(),
    mcpServers: [],
  },
});

제한 사항 (Limitations)

  • 툴 정의: 툴은 AI SDK의 tools 파라미터가 아니라 세션 구성의 MCP 서버를 통해 제공해야 해요
  • 프로세스 수명주기: 각 언어 모델 인스턴스는 새 에이전트 프로세스를 생성해요. 적절한 정리를 보장하세요
  • Node.js 전용: 현재 자식 프로세스 기능이 있는 Node.js 환경을 지원해요
  • 파일 작업: ACP의 클라이언트 인터페이스를 통한 기본 파일 작업 지원
  • 모델 선택: 현재 모델 선택은 아직 지원되지 않아요. 이 기능에 대한 업데이트는 https://github.com/agentclientprotocol/agent-client-protocol/pull/182 참고

추가 리소스 (Additional Resources)

더 알아보기 (Learn more)

전체 사이트맵