tencent cloud

Tencent WorkBuddy Enterprise

DocumentationTencent WorkBuddy EnterpriseCodeBuddyCodeBuddy CodePreferenceACP Protocol Integration

ACP Protocol Integration

Download
Focus Mode
Font Size
Last updated: 2026-09-30 18:15:49
AI-Translated
ACP (Agent Client Protocol) is a universal agent protocol introduced by the Zed editor. It decouples the core functionality (server side) of an agent from its user interface (client side), allowing users to freely choose and pair different agent servers and clients.
CodeBuddy Code natively supports the ACP protocol and can serve as an agent server to seamlessly integrate with ACP-compatible editors.

Quick Start

Starting ACP Mode

Start the ACP server of CodeBuddy Code with the --acp flag:
codebuddy --acp

Zed Editor Integration

Configuration Steps

Open the Zed configuration file (~/.config/zed/settings.json) and add the following configuration:
{
  "agent_servers": {
    "CodeBuddy Code": {
      "command": "codebuddy",
      "args": ["--acp"],
      "env": {}
    }
  }
}
You can then create a CodeBuddy Code Thread in the Zed sidebar to get started.

Configuration Description

command: specifies the command path of CodeBuddy Code (ensure that codebuddy is available in PATH).
args: use ["--acp"] to enable ACP protocol mode.
env: optional environment variable configuration, for example:
{
  "env": {
    "CODEBUDDY_API_KEY": "your-api-key",
    "CODEBUDDY_INTERNET_ENVIRONMENT": "internal"
  }
}
Note:
When using CODEBUDDY_API_KEY, you must correctly configure the CODEBUDDY_INTERNET_ENVIRONMENT environment variable according to your version:
Overseas edition: Not set (default)
China edition: `internal`
iOA edition: `ioa`

ACP Protocol Features

Authentication Information Extension

CodeBuddy Code returns user information in the _meta field of the authenticate response:
{
  "_meta": {
    "codebuddy.ai/userinfo": {
      "userId": "User ID",
      "userName": "Username",
      "userNickname": "User nickname"
    }
  }
}
The client can use this information to provide a better user experience, such as displaying the currently logged-in user and personalizing the interface.

Tool Proxy Mechanism

The ACP protocol supports client-side proxying of some tool operations, improving performance and security:
File operation agent: Based on the client-side fs.readTextFile and fs.writeTextFile capabilities
Terminal operation agent: Based on the client-side terminal capability
When the client declares support for these capabilities, CodeBuddy Code automatically proxies the relevant tool calls to the client for execution.

Command List Push

When creating a new session, CodeBuddy Code automatically pushes the list of available Slash commands to the client (available_commands_update), enabling the client to:
Provide command auto-completion.
Display command prompts and help information.
Dynamically update available commands.
Local commands (such as /clear and /exit) and client-specific commands (such as /theme and /config) are automatically filtered out from the command list, and only commands applicable to ACP mode are pushed.

Agent Teams Protocol Extension

CodeBuddy Code extends the ACP protocol through the _meta field of session_info_update to support real-time status push for Agent Teams multi-agent collaboration.

Team Status Events

Push the following event types through _meta['codebuddy.ai/teamUpdate']:
Member status change (member_status_change):
{
  "sessionUpdate": "session_info_update",
  "_meta": {
    "codebuddy.ai/teamUpdate": {
      "type": "member_status_change",
      "teamName": "my-team",
      "isAutoTeam": false,
      "members": [
        {
          "name": "ux-designer",
          "color": "blue",
          "description": "User experience design analysis",
          "status": "running",
          "taskId": "agent-abc123",
          "sessionId": "session-xyz",
          "tokenUsage": { "inputTokens": 1000, "outputTokens": 500, "lastContextWindow": 42000 },
          "toolCallCount": 5
        }
      ]
    }
  }
}
Team created (team_created) / deleted (team_deleted):
{
  "sessionUpdate": "session_info_update",
  "_meta": {
    "codebuddy.ai/teamUpdate": {
      "type": "team_created",
      "teamName": "my-team"
    }
  }
}

Member Streaming Messages

Real-time messages from members (text, tool calls) are pushed through standard ACP events, with the _meta['codebuddy.ai/memberEvent'] tag attached to identify the message source:
{
  "sessionUpdate": "agent_message_chunk",
  "content": { "type": "text", "text": "Analyzing the architecture solution..." },
  "_meta": {
    "codebuddy.ai/memberEvent": "tech-architect"
  }
}
After receiving an event with the memberEvent tag, the client should route it to the corresponding member's conversation timeline instead of the main conversation area.

Page Refresh Recovery

After the page is refreshed, the current Team status (the member_status_change event) is automatically pushed after the replayHistory of loadSession completes, so the client does not need to make a separate request. When AcpTeamBridge subscribes to a member session, it automatically replays the member's complete history, so the member's conversation data is also fully restored through ACP SSE without additional HTTP APIs.

Support for Other Editors

ACP is an open protocol, and in theory, any ACP-compatible editor can integrate CodeBuddy Code. The configuration is similar to Zed:
{
  "agent_servers": {
    "CodeBuddy": {
      "command": "codebuddy",
      "args": ["--acp"]
    }
  }
}

Troubleshooting

Connection failed

Problem: Zed cannot connect to CodeBuddy.
Solution:
1. Verify that the codebuddy command is available:
which codebuddy
2. Test ACP mode startup:
codebuddy --acp
3. Check whether the JSON format of the configuration file is correct.

Tool Invocation Failures

Problem: Errors occur during file operations or command execution.
Solution:
1. Check the working directory permissions.
2. Check the CodeBuddy logs.

Related Links

CLI Reference Manual: View all command-line parameters.
codebuddy.ai/* Extension Namespace Reference - A complete list of _meta extension keys and _codebuddy.ai/* extension methods, including the public/private boundary.
IDE Integration Guide - More editor integration options
ACP Protocol Specification - Detailed protocol documentation

Previous Topic: IDE IntegrationNext Topic: ACP Extension Namespace Reference

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback

Search
    Enter keywords to search documentation