Practical Guide: Agent Communication Protocol for Local Agents

GitHub Resources and Implementation Patterns

Document ID: STCMastery-ACP-daee8f3e-e23b-4c9a-947d-2bc92abf3c3f
Date: February 7, 2026

1. Quick Start: Experimental ACP Commands

Gemini CLI

```bash

Start Gemini in ACP mode (stdio)

gemini --experimental-acp

Configure for IDE integration (IntelliJ IDEA)

Create/edit ~/.jetbrains/acp.json

{ "agent_servers": { "Gemini CLI": { "command": "/path/to/gemini", "args": ["--experimental-acp"], "use_idea_mcp": true, "use_custom_mcp": true } } } ``` Reference: [cite:16][cite:28]

GitHub Copilot CLI

```bash

Start Copilot as ACP server (stdio mode)

copilot --acp --stdio

Or TCP mode on specific port

copilot --acp --port 8080

Test with TypeScript SDK

npm install @agentclientprotocol/sdk ``` Reference: [cite:17][cite:23][cite:26]

2. Essential GitHub Repositories

Core Protocol Specifications

MCP (Model Context Protocol)

Repository: https://github.com/modelcontextprotocol[cite:18]
Servers: https://github.com/modelcontextprotocol/servers[cite:27]
Microsoft implementations: https://github.com/microsoft/mcp[cite:24]
Documentation: https://modelcontextprotocol.io[cite:8][cite:30]

ACP (Agent Communication Protocol)

Official: https://github.com/agentclientprotocol/agent-client-protocol[cite:37]
BeeAI: https://github.com/i-am-bee/acp[cite:43]
Documentation: https://agentcommunicationprotocol.dev[cite:5][cite:38]

AGI Agent Protocol (Alternative)

Repository: https://github.com/agi-inc/agent-protocol[cite:31][cite:34]
OpenAPI specification for REST-based agent communication

3. SDK Implementations by Language

Python

```bash pip install acp-sdk-python ``` Features: Enterprise-ready with OAuth2, mTLS, API gateway integration[cite:32]

```python from acp_sdk import ACPClient, ACPServer

Create ACP server

server = ACPServer( name="MyAgent", skills=["data_analysis", "summarization"] )

Register agent card

server.register_card( endpoint="http://localhost:8080", auth_method="oauth2" ) ```

TypeScript

```bash npm install @agentclientprotocol/sdk ``` Example: Copilot CLI integration[cite:17][cite:37]

```typescript import * as acp from "@agentclientprotocol/sdk"; import { spawn } from "node:child_process";

const copilotProcess = spawn("copilot", ["--acp", "--stdio"]); const stream = acp.ndJsonStream(output, input); const connection = new acp.ClientSideConnection(client, stream);

await connection.initialize({ protocolVersion: acp.PROTOCOL_VERSION, clientCapabilities: {} }); ```

Rust

```bash cargo add agent-client-protocol ``` Examples: examples/agent.rs and examples/client.rs[cite:37]

Kotlin (JVM)

```kotlin dependencies { implementation("acp-kotlin") } ``` Status: JVM support stable, other targets in progress[cite:37]

4. Example Agent Implementations

All examples available at: https://agentcommunicationprotocol.dev/introduction/example-agents[cite:40]

4.1 Chat Agent with Tools & Memory (BeeAI)

Use case: ReAct agent architecture with tool-based reasoning
GitHub: BeeAI framework examples[cite:40]
Features:

Structured output generation
Tool calling with validation
Memory persistence across sessions

4.2 Slack Agent using MCP

Use case: Demonstrates MCP + ACP integration
Pattern: ACP-compatible agent leveraging MCP Server for Slack API[cite:40]
```bash

Architecture

ACP Client → BeeAI Agent → MCP Slack Server → Slack API ```

4.3 RAG with LlamaIndex

Use case: Retrieval-Augmented Generation via ACP
Framework: LlamaIndex for document retrieval and synthesis[cite:40]
Key concept: Expose retrieval capabilities through ACP's standardized interface

4.4 Multi-Agent Patterns

Prompt Chaining ``` Main Agent → Marketing Copy Agent → Translation Agent ``` Sequential agent invocation for complex workflows[cite:40]

Dynamic Routing ``` Router Agent → [Spanish Agent | French Agent] ``` Language detection and specialized agent routing[cite:40]

Handoff Pattern ``` Main Agent → Spanish Agent (if Spanish detected) Main Agent → English Agent (if English detected) ``` Multilingual delegation with HandoffTool[cite:40]

5. Architecture Patterns for Local Agents

5.1 MCP + ACP Hybrid (Recommended)

``` ┌─────────────────────────────────────────┐ │ Your Agent (ACP Server) │ │ ┌───────────────────────────────────┐ │ │ │ Agent Logic (LLM, Business) │ │ │ └───────────────────────────────────┘ │ │ ▲ │ │ │ │ ▼ │ │ ┌─────────┴─────┬───────────┐ │ │ │ MCP Client │ ACP Server│ │ │ └───────────────┴───────────┘ │ └─────────────────────────────────────────┘ │ ▲ ▼ │ ┌──────────────┐ ┌──────────────┐ │ MCP Servers │ │ Other Agents │ │ (Tools/Data) │ │ (via ACP) │ └──────────────┘ └──────────────┘ ``` Rationale: MCP for tools, ACP for agent coordination[cite:7][cite:50]

5.2 Router Agent with Specialists

``` User → Client Agent → Router Agent │ ┌────────────────┼────────────────┐ ▼ ▼ ▼ Data Agent Code Agent Research Agent │ │ │ └────────────────┴────────────────┘ │ User (Aggregated Results) ``` Pattern: Centralized routing with specialist delegation[cite:5][cite:32][cite:50]
Benefits: Task decomposition, parallel execution, result aggregation

5.3 Multi-Server Discovery

``` Agent Client │ ├─ Discover via HTTP GET /.well-known/agent.json │ ├─ Agent Server 1 (localhost:8080) ├─ Agent Server 2 (localhost:8081) └─ Agent Server 3 (remote.example.com) ``` Discovery mechanism: Agent Cards at standard endpoint[cite:2][cite:5]

6. Educational Resources for Agents

6.1 Official Documentation

ACP Quickstart

URL: https://agentcommunicationprotocol.dev/introduction/quickstart[cite:38]
Covers: Server creation, HTTP interaction, message formats

MCP Core Concepts

URL: https://modelcontextprotocol.io/docs/learn/client-concepts[cite:8]
Covers: Client architecture, lifecycle, primitives

IBM ACP Tutorial

URL: https://www.ibm.com/think/tutorials/acp-ai-agent-interoperability-building-multi-agent-workflows[cite:35]
Hands-on: BeeAI + CrewAI multi-agent workflow

6.2 Academic Papers for Theoretical Foundations

Required Reading:

"A Survey of Agent Interoperability Protocols" (arXiv:2505.02279)[cite:2]
- Comparative analysis of MCP, ACP, A2A, ANP
- Phased adoption roadmap
"A Survey of AI Agent Protocols" (arXiv:2504.16736)[cite:1]
- Two-dimensional classification framework
- Performance metrics: security, scalability, latency
"Beyond Self-Talk: Communication-Centric Survey of LLM-MAS" (arXiv:2502.14321)[cite:33]
- System-level vs internal communication
- Current challenges and benchmarking needs

Supplemental Reading:

"Goal-Oriented Communication in Multi-Agent Systems" (arXiv:2508.07720)[cite:36]
FIPA ACL historical context[cite:47][cite:52][cite:55]

7. Building Your First ACP Agent: Step-by-Step

Step 1: Choose Your Framework

```bash

Option 1: BeeAI (IBM-backed, ACP-native)

npm install @i-am-bee/bee-agent-framework

Option 2: Pure Python SDK

pip install acp-sdk-python

Option 3: Start from scratch with REST

No dependencies needed, just HTTP server

```

Step 2: Define Agent Capabilities

```json { "name": "MyLocalAgent", "version": "1.0.0", "skills": [ { "name": "summarize_text", "description": "Summarizes long text documents", "input_schema": { "type": "object", "properties": { "text": {"type": "string"}, "max_length": {"type": "integer"} } }, "output_schema": { "type": "object", "properties": { "summary": {"type": "string"} } } } ] } ```

Step 3: Implement ACP Server

```python from acp_sdk import ACPServer, Skill

class SummarizationAgent(ACPServer): def init(self): super().init(name="MyLocalAgent") self.register_skill( Skill( name="summarize_text", handler=self.summarize, input_schema=SUMMARIZE_SCHEMA ) )

async def summarize(self, text: str, max_length: int):
    # Your LLM or business logic here
    summary = await self.llm.generate(
        f"Summarize in {max_length} words: {text}"
    )
    return {"summary": summary}

Start server

agent = SummarizationAgent() agent.serve(port=8080) ```

Step 4: Publish Agent Card

```bash

Agent Card automatically served at:

curl http://localhost:8080/.well-known/agent.json

Response:

{ "name": "MyLocalAgent", "version": "1.0.0", "endpoint": "http://localhost:8080", "skills": [...], "authentication": {"type": "none"} } ```

Step 5: Test with Client

```python from acp_sdk import ACPClient

client = ACPClient() agent_card = await client.discover("http://localhost:8080")

result = await client.invoke_skill( agent_card=agent_card, skill_name="summarize_text", inputs={ "text": "Long document...", "max_length": 100 } ) print(result["summary"]) ```

8. Advanced Topics

8.1 Security: OAuth2 + mTLS

```python

Configure ACP server with OAuth2

server = ACPServer( name="SecureAgent", auth_config={ "type": "oauth2", "token_endpoint": "https://auth.example.com/token", "scopes": ["agent:read", "agent:execute"] }, tls_config={ "cert_path": "/path/to/cert.pem", "key_path": "/path/to/key.pem", "ca_path": "/path/to/ca.pem" } ) ``` Reference: Enterprise security patterns[cite:32]

8.2 Observability: Logging and Tracing

```python from acp_sdk import ACPServer import structlog

server = ACPServer( name="ObservableAgent", logger=structlog.get_logger(), enable_tracing=True, trace_exporter="jaeger" )

All requests automatically logged with:

- Request ID

- Agent name

- Skill invoked

- Execution time

- Error traces

```

8.3 Multi-Protocol Support

```python

Agent supporting both ACP and A2A

class HybridAgent: def init(self): self.acp_server = ACPServer(...) self.a2a_server = A2AServer(...)

async def start(self):
    await asyncio.gather(
        self.acp_server.serve(port=8080),
        self.a2a_server.serve(port=8081)
    )

```

9. Troubleshooting Common Issues

Issue 1: Gemini `--experimental-acp` hangs

Cause: Missing --experimental-acp flag or proxy misconfiguration[cite:19]
Solution: Ensure flag is present, check proxy settings

Issue 2: Copilot ACP connection refused

Cause: Port already in use or authentication failure
Solution: Try different port, verify Copilot authentication

Issue 3: MCP Server not found

Cause: Incorrect stdio configuration or server not started
Solution: Verify MCP server command in config, check server logs

Issue 4: Agent Card 404

Cause: Agent Card not published at standard endpoint
Solution: Ensure /.well-known/agent.json route is configured

10. Next Steps and Learning Path

For Beginners

Read academic survey (academic-survey.md)[cite:60]
Install Gemini CLI or Copilot CLI
Run experimental ACP commands
Explore MCP example servers[cite:21][cite:27]

For Intermediate Developers

Build simple ACP agent with Python SDK[cite:32]
Integrate MCP server for tool access[cite:24]
Implement router agent pattern[cite:5][cite:50]
Study BeeAI examples[cite:40][cite:43]

For Advanced Practitioners

Design multi-agent workflow with ACP + A2A
Implement enterprise security (OAuth2, mTLS)[cite:32]
Build domain-specific protocol extensions
Contribute to open-source protocol implementations[cite:37][cite:43]

11. Community and Standards Organizations

Linux Foundation Agentic AI Foundation

Governance for MCP
Announcement: December 2025[cite:51][cite:57]

W3C AI Agent Protocol Community Group

Official web standards development
Expected: 2026-2027[cite:51]

AGNTCY Coalition

Members: Cisco, LangChain, LlamaIndex, Galileo, Glean[cite:6]
Focus: "Internet of Agents" infrastructure

IBM Research + BeeAI

ACP development and maintenance[cite:7][cite:11][cite:43]

12. Claude-Code Skill: ACP Protocol Understanding

```markdown

ACP Protocol Expert Skill

Skill Name

acp_protocol_expert

Description

Enables Claude to understand and work with Agent Communication Protocol (ACP), Model Context Protocol (MCP), and related agent interoperability standards.

Knowledge Base

Four core protocols: MCP, ACP, A2A, ANP
Protocol architectures and lifecycles
SDK implementations (Python, TypeScript, Rust, Kotlin)
Security patterns (OAuth2, mTLS, observability)
Multi-agent orchestration patterns
GitHub repositories and example implementations

Capabilities

Explain Protocol Concepts: Describe ACP, MCP, A2A, ANP architectures
Generate Code Examples: Produce working agent implementations
Debug Protocol Issues: Troubleshoot connectivity, auth, discovery problems
Design Multi-Agent Systems: Architect hybrid MCP+ACP workflows
Security Analysis: Review and recommend security configurations
SDK Selection: Advise on framework choices (BeeAI, LangChain, custom)

Usage Examples

Example 1: Create ACP Agent

Input: "Create a Python ACP agent that summarizes documents" Output: Complete Python code with ACPServer, skill definition, and deployment

Example 2: Explain Protocol Difference

Input: "What's the difference between MCP and ACP?" Output: MCP = agent↔tools, ACP = agent↔agent, with architecture diagrams

Example 3: Troubleshoot Integration

Input: "My Gemini --experimental-acp flag isn't working" Output: Diagnostic steps, config verification, proxy checks

Example 4: Design Architecture

Input: "Design a multi-agent system for customer support" Output: Router agent → [FAQ Agent, Ticket Agent, Escalation Agent] with ACP

Learning Resources

Academic papers: arXiv:2504.16736, arXiv:2505.02279
Official docs: agentcommunicationprotocol.dev, modelcontextprotocol.io
GitHub: agentclientprotocol/agent-client-protocol, i-am-bee/acp
Tutorials: IBM ACP multi-agent workflows

Status

Active - Updated February 2026 ```

Document prepared for: Local agent self-education
Maintenance: Update as protocols evolve toward W3C standardization
Support: Consult official documentation and GitHub issues for latest changes

Practical Guide: Agent Communication Protocol for Local Agents

Practical Guide: Agent Communication Protocol for Local Agents

GitHub Resources and Implementation Patterns

1. Quick Start: Experimental ACP Commands

Gemini CLI

Start Gemini in ACP mode (stdio)

Configure for IDE integration (IntelliJ IDEA)

Create/edit ~/.jetbrains/acp.json

GitHub Copilot CLI

Start Copilot as ACP server (stdio mode)

Or TCP mode on specific port

Test with TypeScript SDK

2. Essential GitHub Repositories

Core Protocol Specifications

3. SDK Implementations by Language

Python

Create ACP server

Register agent card

TypeScript

Rust

Kotlin (JVM)

4. Example Agent Implementations

4.1 Chat Agent with Tools & Memory (BeeAI)

4.2 Slack Agent using MCP

Architecture

4.3 RAG with LlamaIndex

4.4 Multi-Agent Patterns

5. Architecture Patterns for Local Agents

5.1 MCP + ACP Hybrid (Recommended)

5.2 Router Agent with Specialists

5.3 Multi-Server Discovery

6. Educational Resources for Agents

6.1 Official Documentation

6.2 Academic Papers for Theoretical Foundations

7. Building Your First ACP Agent: Step-by-Step

Step 1: Choose Your Framework

Option 1: BeeAI (IBM-backed, ACP-native)

Option 2: Pure Python SDK

Option 3: Start from scratch with REST

No dependencies needed, just HTTP server

Step 2: Define Agent Capabilities

Step 3: Implement ACP Server

Start server

Step 4: Publish Agent Card

Agent Card automatically served at:

Response:

Step 5: Test with Client

8. Advanced Topics

8.1 Security: OAuth2 + mTLS

Configure ACP server with OAuth2

8.2 Observability: Logging and Tracing

All requests automatically logged with:

- Request ID

- Agent name

- Skill invoked

- Execution time

- Error traces

8.3 Multi-Protocol Support

Agent supporting both ACP and A2A

9. Troubleshooting Common Issues

Issue 1: Gemini --experimental-acp hangs

Issue 2: Copilot ACP connection refused

Issue 3: MCP Server not found

Issue 4: Agent Card 404

10. Next Steps and Learning Path

For Beginners

For Intermediate Developers

For Advanced Practitioners

11. Community and Standards Organizations

12. Claude-Code Skill: ACP Protocol Understanding

ACP Protocol Expert Skill

Skill Name

Description

Knowledge Base

Capabilities

Usage Examples

Example 1: Create ACP Agent

Example 2: Explain Protocol Difference

Example 3: Troubleshoot Integration

Example 4: Design Architecture

Issue 1: Gemini `--experimental-acp` hangs