AcpSdk 1.2.0

ACP SDK for .NET

A modern, AOT-compatible .NET SDK for the Agent Client Protocol (ACP) - enabling seamless communication between AI coding assistants and IDE extensions using JSON-RPC 2.0.

Overview

ACP SDK provides a robust implementation of the Agent Client Protocol, built on top of Microsoft's StreamJsonRpc library. This unified SDK enables developers to:

• Build IDE Extensions: Create Visual Studio, VS Code, or other IDE extensions that communicate with AI coding assistants
• Implement AI Agents: Build AI agent backends that respond to client requests
• Bidirectional Communication: Full support for requests, notifications, and streaming updates

All components (Client, Server, Protocol) are integrated into a single, lightweight package (AcpSdk).

Architecture

┌─────────────────┐                      ┌─────────────────┐
│    IDE/Client   │                      │    AI Agent     │
│                 │                      │                 │
│  ┌───────────┐  │   StreamJsonRpc      │  ┌───────────┐  │
│  │AcpSdk.Client│◄─┼──────────────────────┼─►│AcpSdk.Server│  │
│  └───────────┘  │   (JSON-RPC 2.0)     │  └───────────┘  │
│                 │                      │                 │
│  ┌──────────────┐  │                      │  ┌──────────────┐  │
│  │AcpSdk.Protocol│ │                      │  │AcpSdk.Protocol│ │
│  └──────────────┘  │                      │  └──────────────┘  │
└─────────────────┘                      └─────────────────┘

Namespaces

Features

• AOT Compatible: Full support for Native AOT compilation using source generators
• StreamJsonRpc Integration: Built on Microsoft's production-grade JSON-RPC library
• Multi-target: Supports .NET 8.0, .NET 9.0, and .NET Standard 2.1
• Type-safe: Strongly-typed request/response models with polymorphic serialization
• Streaming Updates: Real-time session updates via notifications
• Terminal Support: Full terminal emulation protocol
• MCP Integration: Support for Model Context Protocol servers
• HTTP/SSE Transport: Full support for HTTP POST/SSE communication (ideal for web/cloud agents)

Installation

# Install the SDK package (includes Client, Server, and Protocol)
dotnet add package AcpSdk

For projects that support PackageReference, copy this XML node into the project file to reference the package:

<PackageReference Include="AcpSdk" Version="1.2.0" />

Quick Start

Client Usage (IDE Extension)

using AcpSdk.Client;
using AcpSdk.Protocol.Abstractions;
using AcpSdk.Protocol.Core.Constants;
using AcpSdk.Protocol.Models;
using AcpSdk.Protocol.Models.Contents;
using AcpSdk.Protocol.Models.Files;
using AcpSdk.Protocol.Models.Initialize;
using AcpSdk.Protocol.Models.Prompts;
using AcpSdk.Protocol.Models.Session;

// Implement the client handler for incoming requests from the agent
public class MyClientHandler : IAcpClient
{
    public ValueTask<ReadTextFileResponse> ReadTextFileAsync(ReadTextFileRequest request, CancellationToken ct)
    {
        var content = File.ReadAllText(request.Path);
        return ValueTask.FromResult(new ReadTextFileResponse { Content = content });
    }

    public ValueTask OnSessionNotificationAsync(SessionNotification notification, CancellationToken ct)
    {
        // Handle streaming updates
        Console.WriteLine($"Session update: {notification.Update}");
        return ValueTask.CompletedTask;
    }

    // ... implement other methods
}

// Connect to an agent process
var process = new Process
{
    StartInfo = new ProcessStartInfo("path/to/agent")
    {
        RedirectStandardInput = true,
        RedirectStandardOutput = true,
        UseShellExecute = false
    }
};
process.Start();

var clientHandler = new MyClientHandler();
// Uses implicit CreateNewLineDelimited (NDJSON) framing by default for processes
var connection = AcpClientConnection.CreateForProcess(process, clientHandler);
connection.StartListening();

// Initialize the connection
var initResponse = await connection.InitializeAsync(new InitializeRequest
{
    ProtocolVersion = ProtocolConstants.ProtocolVersion,
    ClientInfo = new Implementation { Name = "MyIDE", Version = "1.0.0" }
});

// Create a session
var session = await connection.NewSessionAsync(new NewSessionRequest
{
    Cwd = Environment.CurrentDirectory,
    McpServers = []
});

// Send a prompt
var response = await connection.PromptAsync(new PromptRequest
{
    SessionId = session.SessionId,
    Prompt = [new TextContentBlock { Text = "Hello, agent!" }]
});

Remote Agent Connection (HTTP/SSE)

For connecting to a remote agent or a containerized agent that exposes HTTP/SSE endpoints:

using AcpSdk.Client;
using System.Net.Http;

// ... Create your client handler ...

// Connect to an agent via HTTP/SSE
// The SDK will use POST /rpc for sending and GET /events for receiving
var httpClient = new HttpClient();
var connection = AcpClientConnectionExtensions.CreateHttpSse(
    "http://localhost:5000/agent", 
    httpClient, 
    clientHandler
);

// Start listening for SSE events
// connection.StartListening() is called automatically for SSE, so you can proceed to InitializeAsync
var initResponse = await connection.InitializeAsync(new InitializeRequest { ... });

Server Usage (AI Agent)

using AcpSdk.Server;
using AcpSdk.Protocol.Abstractions;
using AcpSdk.Protocol.Core.Constants;
using AcpSdk.Protocol.Models;
using AcpSdk.Protocol.Models.Authentication;
using AcpSdk.Protocol.Models.Initialize;
using AcpSdk.Protocol.Models.Prompts;

// Implement the agent handler
public class MyAgentHandler : IAcpAgent
{
    public ValueTask<InitializeResponse> InitializeAsync(InitializeRequest request, CancellationToken ct)
    {
        return ValueTask.FromResult(new InitializeResponse
        {
            ProtocolVersion = ProtocolConstants.ProtocolVersion,
            AgentInfo = new Implementation { Name = "MyAgent", Version = "1.0.0" },
            AuthMethods = [new AuthMethod { Id = "none", Label = "No Auth" }]
        });
    }

    public ValueTask<PromptResponse> PromptAsync(PromptRequest request, CancellationToken ct)
    {
        // Process the prompt and stream updates
        return ValueTask.FromResult(new PromptResponse
        {
            StopReason = StopReason.EndTurn
        });
    }

    // ... implement other methods
}

// Start the server (Standard Input/Output = NDJSON)
var agentHandler = new MyAgentHandler();
var connection = AcpServerConnection.CreateForConsole(agentHandler);
connection.StartListening();

// Wait for the connection to close
await connection.Completion;

Configuration

The SDK provides a simple way to load agent configuration from a JSON file using AgentConfigurationLoader. This is useful for switching between local and remote agents without changing code.

using AcpSdk.Client.Configuration;
using AcpSdk.Client.Factories;

// Load configuration
var config = AgentConfigurationLoader.Load("agent.config.json");

// Create connection using the factory
// This automatically handles validation and local/remote logic
var connection = await AcpClientFactory.CreateFromConfigAsync(config, clientHandler);

connection.StartListening();

Configuration File Example (agent.config.json)

Local Agent:

{
  "type": "local",
  "local": {
    "command": "path/to/agent.exe",
    "arguments": ["--verbose"],
    "workingDirectory": "."
  }
}

Remote Agent:

{
  "type": "remote",
  "remote": {
    "url": "http://localhost:5000/agent",
    "transport": "sse"
  }
}

Protocol Methods

Agent Methods (Client → Agent)

Client Methods (Agent → Client)

Session Updates

The SDK supports streaming session updates including:

• user_message_chunk - Echoed user input
• agent_message_chunk - Agent response chunks
• agent_thought_chunk - Agent reasoning (when visible)
• tool_call - Tool invocation details
• tool_call_update - Incremental tool progress
• plan - Agent planning information
• available_commands_update - Available slash commands
• current_mode_update - Current session mode

Content Types

The protocol supports multiple content types through polymorphic serialization:

• Text - Plain text content
• Image - Base64-encoded images
• Audio - Audio data
• Resource - MCP resource references
• Resource Link - Links to MCP resources

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Support

• Documentation
• Issues
• Discussions