[Feature]: Agent Client Protocol(ACP) support

[Tim-Rambo]

Why you want this Feature?

Gemini wrote this better than what I could.

PS generated with AI

Describe the solution you'd like

Being able to create an agent with ACP to where I can harness the power of Aigne in Zed and other code editors that support ACP.

Additional context

From the Zed IDE.
https://zed.dev/blog/bring-your-own-agent-to-zed

ACP Website
https://agentclientprotocol.com/overview/introduction

From Google
https://developers.googleblog.com/en/gemini-cli-is-now-integrated-into-zed/

Claude-Code ACP Adapter Repo
https://github.com/zed-industries/claude-code-acp

Claude Code: Now in Beta in Zed [BLOG post]
https://zed.dev/blog/claude-code-via-acp

[Tim-Rambo]

Perplexity chat Link

I would think this would be a massive power move to be ahead of the curve and implement ACP into the Aigne Framework.

[Tim-Rambo]

Perplexity Chat Link

acp-implementation-guide.md

Implementing Agent Client Protocol (ACP) in AIGNE Framework

Executive Summary

This comprehensive guide outlines how to implement the Agent Client Protocol (ACP) from Zed Industries into the AIGNE Framework, enabling AIGNE agents to communicate seamlessly with code editors like Zed, Neovim, and other ACP-compatible clients.

Current AIGNE Architecture Analysis

Existing Communication Patterns

• Model Context Protocol (MCP): External tool/service integration via JSON-RPC
• Agent-to-Agent Communication: Internal communication through AIGNE Environment
• TypeScript-based Core: Modular design with comprehensive type definitions
• Multi-Agent Workflows: Support for sequential, concurrent, routing, and handoff patterns

Agent Types in AIGNE

• AIAgent: LLM-powered agents with model integration
• MCPAgent: Bridge agents for MCP server communication
• FunctionAgent: Task-specific functional agents
• Multi-agent Systems: Coordinated agent collaboration

Agent Client Protocol Overview

Core Concepts

• Purpose: Standardizes communication between code editors and AI coding agents
• Transport: JSON-RPC 2.0 over stdio (stdin/stdout)
• Architecture: Bidirectional client-server communication
• Protocol Version: 1 (current)

Communication Model

• Methods: Request-response pairs expecting results or errors
• Notifications: One-way messages requiring no response
• Sessions: Isolated conversation contexts with persistent state

Implementation Approaches

Recommended Approach: Hybrid ACPAgent + Protocol Adapter

Rationale:

• Minimal disruption to existing AIGNE architecture
• Quick implementation and testing capability
• Clear migration path for future core integration
• Leverages existing MCP infrastructure patterns

Benefits:

• Clean separation of concerns
• Non-intrusive to existing agent functionality
• Can wrap any existing AIGNE agent
• Supports incremental feature rollout

Technical Implementation Plan

Phase 1: Basic ACP Support

1. ACPAgent Class Implementation

import { Agent, AIAgent, AIGNE } from "@aigne/core";
import { AgentSideConnection, InitializeRequest, InitializeResponse } from "@zed-industries/agent-client-protocol";

export class ACPAgent extends Agent {
  private connection: AgentSideConnection;
  private wrappedAgent: AIAgent;
  private sessions: Map<string, SessionContext> = new Map();
  
  constructor(agent: AIAgent, options: ACPAgentOptions) {
    super();
    this.wrappedAgent = agent;
    this.setupACPConnection();
  }
  
  private setupACPConnection() {
    this.connection = new AgentSideConnection({
      initialize: this.handleInitialize.bind(this),
      newSession: this.handleNewSession.bind(this),
      prompt: this.handlePrompt.bind(this),
      // ... other ACP method handlers
    });
  }
}

2. JSON-RPC Server Setup

class ACPServer {
  private agent: ACPAgent;
  
  constructor(agent: ACPAgent) {
    this.agent = agent;
    this.setupStdioTransport();
  }
  
  private setupStdioTransport() {
    // Handle JSON-RPC over stdin/stdout
    process.stdin.setEncoding('utf8');
    process.stdin.on('data', this.handleMessage.bind(this));
  }
  
  private handleMessage(data: string) {
    const messages = data.trim().split('\n');
    for (const message of messages) {
      try {
        const jsonRpc = JSON.parse(message);
        this.agent.connection.handleMessage(jsonRpc);
      } catch (error) {
        // Handle parsing errors
      }
    }
  }
}

3. Session Management

interface SessionContext {
  id: string;
  agent: AIAgent;
  environment: AIGNE;
  history: MessageHistory;
  mcpServers: MCPServer[];
  workingDirectory: string;
}

class SessionManager {
  private sessions = new Map<string, SessionContext>();
  
  async createSession(request: NewSessionRequest): Promise<SessionContext> {
    const sessionId = generateSessionId();
    const environment = new AIGNE({ 
      model: this.wrappedAgent.model,
      workingDirectory: request.cwd 
    });
    
    // Connect MCP servers
    const mcpAgents = await this.connectMCPServers(request.mcpServers);
    
    const session: SessionContext = {
      id: sessionId,
      agent: this.wrappedAgent,
      environment,
      history: new MessageHistory(),
      mcpServers: request.mcpServers,
      workingDirectory: request.cwd
    };
    
    this.sessions.set(sessionId, session);
    return session;
  }
}

4. Basic Method Handlers

class ACPAgent extends Agent {
  async handleInitialize(request: InitializeRequest): Promise<InitializeResponse> {
    return {
      protocolVersion: 1,
      agentCapabilities: {
        loadSession: false, // Initially false, implement in Phase 2
        promptCapabilities: {
          image: false,
          audio: false,
          embeddedContext: true
        },
        mcpCapabilities: {
          http: true,
          sse: true
        }
      },
      authMethods: []
    };
  }
  
  async handleNewSession(request: NewSessionRequest): Promise<NewSessionResponse> {
    const session = await this.sessionManager.createSession(request);
    return {
      sessionId: session.id,
      modes: null // Implement session modes in Phase 2
    };
  }
  
  async handlePrompt(request: PromptRequest): Promise<PromptResponse> {
    const session = this.sessions.get(request.sessionId);
    
    // Convert ACP content blocks to AIGNE format
    const prompt = this.convertContentBlocks(request.prompt);
    
    // Stream updates via notifications
    this.streamUpdates(session, prompt);
    
    // Process with wrapped AIGNE agent
    const response = await session.agent.invoke(prompt);
    
    return {
      stopReason: "end_turn"
    };
  }
}

Phase 2: Enhanced Features

File System Operations

async handleReadTextFile(request: ReadTextFileRequest): Promise<ReadTextFileResponse> {
  const session = this.sessions.get(request.sessionId);
  const content = await fs.readFile(request.path, 'utf8');
  
  // Apply line limits if specified
  if (request.line || request.limit) {
    const lines = content.split('\n');
    const startLine = (request.line || 1) - 1;
    const endLine = request.limit ? startLine + request.limit : lines.length;
    return { content: lines.slice(startLine, endLine).join('\n') };
  }
  
  return { content };
}

async handleWriteTextFile(request: WriteTextFileRequest): Promise<WriteTextFileResponse> {
  await fs.writeFile(request.path, request.content, 'utf8');
  return {};
}

Terminal Support

class TerminalManager {
  private terminals = new Map<string, TerminalSession>();
  
  async createTerminal(request: CreateTerminalRequest): Promise<CreateTerminalResponse> {
    const terminalId = generateTerminalId();
    const terminal = spawn(request.command, request.args, {
      cwd: request.cwd || process.cwd(),
      env: { ...process.env, ...this.parseEnvVariables(request.env) }
    });
    
    const session: TerminalSession = {
      id: terminalId,
      process: terminal,
      output: '',
      exitStatus: null
    };
    
    this.terminals.set(terminalId, session);
    return { terminalId };
  }
}

Permission System

async handleRequestPermission(
  request: RequestPermissionRequest
): Promise<RequestPermissionResponse> {
  // Send permission request to client
  const response = await this.connection.requestPermission({
    sessionId: request.sessionId,
    toolCall: request.toolCall,
    options: [
      { optionId: "allow_once", name: "Allow Once", kind: "allow_once" },
      { optionId: "allow_always", name: "Always Allow", kind: "allow_always" },
      { optionId: "reject_once", name: "Deny", kind: "reject_once" }
    ]
  });
  
  return response;
}

Phase 3: Advanced Integration

Multi-Agent Session Support

class MultiAgentSession extends SessionContext {
  private agents: Map<string, AIAgent> = new Map();
  private currentAgent: string;
  
  async switchAgent(agentId: string): Promise<void> {
    if (!this.agents.has(agentId)) {
      throw new Error(`Agent ${agentId} not found in session`);
    }
    this.currentAgent = agentId;
    
    // Notify client of agent switch
    await this.notifySessionUpdate({
      sessionUpdate: "current_mode_update",
      currentModeId: agentId
    });
  }
}

MCP Server Passthrough

async connectMCPServers(servers: McpServer[]): Promise<MCPAgent[]> {
  const mcpAgents: MCPAgent[] = [];
  
  for (const server of servers) {
    let mcpAgent: MCPAgent;
    
    if (server.type === 'stdio') {
      mcpAgent = await MCPAgent.from({
        command: server.command,
        args: server.args,
        env: server.env
      });
    } else if (server.type === 'http' || server.type === 'sse') {
      mcpAgent = await MCPAgent.from({
        url: server.url,
        transport: server.type,
        headers: server.headers
      });
    }
    
    mcpAgents.push(mcpAgent);
  }
  
  return mcpAgents;
}

Integration Points with AIGNE

1. AIGNE Environment Integration

// Extend AIGNE Environment to support ACP sessions
class ACPAwareEnvironment extends AIGNE {
  private acpSession?: SessionContext;
  
  setACPSession(session: SessionContext) {
    this.acpSession = session;
    this.workingDirectory = session.workingDirectory;
  }
  
  async invoke(agent: Agent, input: any): Promise<any> {
    // Integrate with ACP streaming updates
    if (this.acpSession) {
      this.setupACPStreaming(this.acpSession);
    }
    
    return super.invoke(agent, input);
  }
}

2. Content Block Conversion

function convertACPContentToAIGNE(blocks: ContentBlock[]): string {
  return blocks.map(block => {
    switch (block.type) {
      case 'text':
        return block.text;
      case 'resource_link':
        return `[Resource: ${block.name}](${block.uri})`;
      case 'resource':
        return `[Embedded: ${block.resource.uri}]\n${block.resource.text || block.resource.blob}`;
      default:
        return '';
    }
  }).join('\n\n');
}

function convertAIGNEToACPContent(response: string): ContentBlock[] {
  return [{
    type: 'text',
    text: response
  }];
}

3. Tool Call Integration

async handleToolCalls(toolCalls: ToolCall[]): Promise<void> {
  for (const toolCall of toolCalls) {
    // Check if permission required
    if (this.requiresPermission(toolCall)) {
      const permission = await this.requestPermission(toolCall);
      if (!this.isPermissionGranted(permission)) {
        continue;
      }
    }
    
    // Execute tool call through AIGNE
    const result = await this.executeToolCall(toolCall);
    
    // Update client with results
    await this.notifyToolCallUpdate({
      toolCallId: toolCall.toolCallId,
      status: 'completed',
      content: this.formatToolCallContent(result)
    });
  }
}

Deployment and Usage

1. Package Structure

@aigne/acp/
├── src/
│   ├── ACPAgent.ts
│   ├── ACPServer.ts
│   ├── SessionManager.ts
│   ├── TerminalManager.ts
│   └── index.ts
├── examples/
│   ├── basic-agent.ts
│   └── multi-agent.ts
└── package.json

2. Usage Example

import { AIAgent, AIGNE } from "@aigne/core";
import { OpenAIChatModel } from "@aigne/openai";
import { ACPAgent, ACPServer } from "@aigne/acp";

// Create base AIGNE agent
const model = new OpenAIChatModel({ apiKey: process.env.OPENAI_API_KEY });
const agent = AIAgent.from({
  name: "CodeAssistant",
  instructions: "You are a helpful coding assistant.",
  model
});

// Wrap with ACP support
const acpAgent = new ACPAgent(agent, {
  capabilities: {
    fileSystem: { readTextFile: true, writeTextFile: true },
    terminal: true,
    image: false,
    audio: false
  }
});

// Start ACP server
const server = new ACPServer(acpAgent);
server.start();

3. Configuration for Code Editors

Zed Configuration

{
  "agents": {
    "aigne": {
      "command": "node",
      "args": ["path/to/aigne-acp-agent.js"],
      "name": "AIGNE Assistant"
    }
  }
}

Neovim (CodeCompanion) Configuration

require("codecompanion").setup({
  adapters = {
    aigne = function()
      return require("codecompanion.adapters").extend("openai", {
        name = "aigne",
        command = "node path/to/aigne-acp-agent.js",
        schema = {
          model = { default = "aigne-agent" }
        }
      })
    end
  }
})

Testing Strategy

1. Unit Tests

• ACP method handlers
• Content block conversion
• Session management
• Protocol compliance

2. Integration Tests

• End-to-end communication with Zed
• Multi-session handling
• MCP server integration
• File system operations

3. Performance Tests

• Message throughput
• Memory usage with multiple sessions
• Terminal operation efficiency

Migration Path and Compatibility

Backward Compatibility

• Existing AIGNE agents work unchanged
• MCP integration remains functional
• No breaking changes to core API

Forward Compatibility

• Extensible capability system
• Custom method support via _meta fields
• Protocol version negotiation

Conclusion

Implementing ACP in AIGNE Framework provides significant benefits:

1. Universal Editor Support: AIGNE agents work in any ACP-compatible editor
2. Standardized Interface: Consistent user experience across development environments
3. Enhanced Capabilities: Rich editor integration with file operations, terminals, and permissions
4. Future-Proof Architecture: Built on open standards with industry backing

The recommended hybrid approach ensures rapid implementation while maintaining architectural flexibility for future enhancements. This positions AIGNE as a leading framework in the emerging standardized AI agent ecosystem.

I made the AI do some comprehensive research with how to implement ACP to AIGNE by using a link to this github issue.

The implementation would transform AIGNE from a powerful backend framework into a comprehensive AI development ecosystem that seamlessly bridges intelligent agents with developer workflows, establishing it as a cornerstone technology in the emerging AI-native development landscape.