ACP (Agent Client Protocol) server that wraps @tsagent/core agents
npm install @tsagent/acp-serverAn ACP (Agent Client Protocol) server implementation that wraps agents created with the @tsagent/core package. This server provides stdio-based communication following the ACP protocol specification, enabling integration with ACP-compatible code editors (like Zed).
This package is part of TSAgent, an open-source TypeScript-first platform for building, testing, running, and orchestrating AI agents.
- Main Project: TSAgent Repository
- Documentation: Full Documentation
- Issues & Support: GitHub Issues
- ACP Protocol Compliance: Implementation of the Agent Client Protocol specification
- stdio Communication: JSON-RPC over stdio for subprocess-based communication
- Agent Integration: Wraps @tsagent/core agents with ACP protocol interface
- Session Management: Handles multiple concurrent client sessions
- Tool Support: Supports tool calls between client and agent
- Graceful Shutdown: Proper cleanup and resource management
- CLI Interface: Command-line interface for easy server invocation
``bash`
npm install @tsagent/acp-server
The ACP server is designed to run as a subprocess invoked by ACP-compatible clients (like code editors):
`bashStart ACP server with an agent (absolute path)
tsagent-acp-server /path/to/my-agent.yaml
Via CLI Launcher:
`bash
Launch ACP server via tsagent CLI
tsagent --acp /path/to/agent.yaml
tsagent --acp agent.yaml --debug
`$3
`typescript
import { ACPServer } from '@tsagent/acp-server';// Create and start an ACP server for an agent
const server = new ACPServer('/path/to/agent.yaml', {
verbose: false // Use debug flag for verbose logging
});
await server.start();
// Server is now ready to communicate via stdio
// The SDK handles JSON-RPC communication automatically
`Command Line Options:
-
: Path to the agent file (.yaml or .yml) - required
- Absolute path: /path/to/agent.yaml - uses path as-is
- Relative filename: agent.yaml - looks in current working directory
- --debug, -d: Enable debug/verbose logging
- --help, -h: Show help messageAgent Configuration
Agents are configured using a single YAML file (
.yaml or .yml). All agent content (system prompt, rules, references) is embedded in the file:`yaml
metadata:
name: "My Assistant"
description: "A helpful AI assistant"
# ... other metadata fieldssystemPrompt: |
You are a helpful AI assistant.
This is a multi-line system prompt.
Supports markdown formatting.
rules:
- name: "example-rule"
description: "An example rule"
priorityLevel: 500
text: |
Rule content here.
Supports markdown.
include: "always"
references:
- name: "example-reference"
description: "An example reference"
priorityLevel: 500
text: |
Reference content here.
Supports markdown.
include: "manual"
... providers, mcpServers, etc.
`
ACP Protocol Methods
The server implements the following ACP protocol methods:
-
initialize - Negotiate protocol version and capabilities
- session/new - Create a new ACP session (supports client-provided MCP servers)
- session/prompt - Send a prompt to the agent within a session
- session/cancel - Cancel an in-progress prompt (notification)MCP Tool Sharing
ACP enables clients to pass their own MCP servers to agents during session creation, allowing agents to access client-configured tools and context. See MCP Tool Sharing Documentation for details on how this works and the implementation plan.
Architecture
$3
- Protocol: JSON-RPC over stdio (stdin/stdout)
- Transport: Handled automatically by
@agentclientprotocol/sdk
- Sessions: One ACP session = One agent chat session$3
- Each ACP session maps to a
@tsagent/core chat session
- Sessions maintain conversation history and context
- Sessions can be created, used for prompts, and closed$3
- ACP → Agent: Converts ACP content (Markdown, text, diffs) to agent message format
- Agent → ACP: Converts agent responses to ACP content format (Markdown by default)
- Tool calls are handled and forwarded between client and agent
Integration with Code Editors
$3
To use this server with Zed editor:
1. Configure Zed to use the ACP server as an agent
2. Zed will spawn the server as a subprocess
3. Communication happens via stdio (JSON-RPC)
Example Zed configuration (if applicable):
`json
{
"acp_agents": {
"tsagent": {
"command": "tsagent",
"args": ["--acp", "/path/to/agent.yaml"]
}
}
}
`Or using the server binary directly:
`json
{
"acp_agents": {
"tsagent": {
"command": "tsagent-acp-server",
"args": ["/path/to/agent.yaml"]
}
}
}
`Note: Actual configuration format depends on Zed's ACP implementation
Development
`bash
Build the package
npm run buildRun in development mode
npm run dev /path/to/agent.yaml
npm run dev agent.yaml # Relative filenameStart server
npm start /path/to/agent.yaml
npm start agent.yaml # Relative filename
`Implementation Status
⚠️ Work in Progress: This package is currently under active development. The core structure is in place, but SDK integration is pending verification of the
@agentclientprotocol/sdk API.$3
- ✅ Package structure
- ✅ Logger implementation
- ✅ Session manager
- ✅ Agent handler (content conversion)
- ✅ Basic server class structure
- ✅ CLI interface$3
- ⏳ SDK integration (AgentSideConnection setup)
- ⏳ Protocol method handler registration
- ⏳ Transport connection setup
- ⏳ Testing with ACP clients
- ⏳ Tool call handling refinementRelated Packages
-
@tsagent/core - Core TypeScript agent framework
- @tsagent/server - A2A protocol server (HTTP-based)
- @tsagent/cli` - Command-line interface for agent operationsMIT License - see LICENSE for details.