Agent-CAN Bus

TypeScript LAN service for Agent-to-Agent communication architecture.

This project is only the communication layer:

• agent registration and discovery
• CAN-style numeric node addressing
• frame routing
• ACK / STAT / RES / ERR flow
• request-response waiting by correlation id
• queue, audit, approvals
• MCP bridge for controlling the bus from Codex
• A2A-inspired field model: AgentCard/Skill, Task, Message, Part, Artifact, Status

It does not implement business tools. Weather, filesystem, browser, ERP, MES, CRM, or shell execution must live inside an external agent runtime.

Run

pnpm install
pnpm build
pnpm start

Install For Other Machines

After publishing or sharing the package tarball, other machines can install it as a normal npm package.

Global install from npm:

npm install -g @donwei123/agent-can-bus

Local install from a packed tarball:

npm install -g ./donwei123-agent-can-bus-0.1.0.tgz

Then register Codex MCP and Agent-CAN skills:

agent-can-setup-codex \
  --bus-url http://192.168.1.168:8787 \
  --token dev-agent-can-token

This writes:

• MCP server id: agent-can-bus
• MCP tools: agent_can_health, agent_can_list_agents, agent_can_request_task, and related bus tools
• Skills: agent-can-bus, agent-can-protocol, agent-can-ops, agent-can-runtime

Restart Codex CLI after setup. Then a user can ask:

用 Agent-CAN 问 can:2：你好

The setup command intentionally runs explicitly instead of as postinstall; installing an npm package should not silently rewrite Codex config.

Package commands:

agent-can-server
agent-can-runtime
agent-can-mcp
agent-can-setup-codex

Default endpoints:

• Management UI: http://127.0.0.1:8787/
• HTTP: http://127.0.0.1:8787
• WebSocket: ws://127.0.0.1:8787/ws
• Health: GET /health
• Agents: GET /agents
• Frames: GET /frames
• Request/response: POST /tasks/request
• Queue: GET /queue
• Approvals: GET /approvals
• Audit: GET /audit
• A2A card draft: GET /a2a/agent-card

Default development token:

dev-agent-can-token

Use it as Authorization: Bearer dev-agent-can-token, x-agent-can-token, or WebSocket query ?token=dev-agent-can-token.

Runtime Agent

The included runtime agent is a protocol entrypoint. It registers on the bus, accepts TASK frames, immediately returns STAT ack.accepted, then either:

• calls a configured external executor and returns RES
• returns ERR runtime.not_configured when no executor is configured

The bus stays communication-only. Cursor, Codex, Python agents, shell tools, RAG, ERP, MES, CRM, or file access must be connected behind the runtime as external executors.

AGENT_CAN_WS=ws://127.0.0.1:8787/ws \
AGENT_CAN_TOKEN=dev-agent-can-token \
AGENT_ID=runtime_agent \
AGENT_CAN_ID=2 \
pnpm agent:runtime

Echo executor for transport testing:

AGENT_CAN_WS=ws://127.0.0.1:8787/ws \
AGENT_CAN_TOKEN=dev-agent-can-token \
AGENT_ID=runtime_agent \
AGENT_CAN_ID=2 \
AGENT_CAN_EXECUTOR_COMMAND=/bin/echo \
pnpm agent:runtime

Cursor Agent CLI executor:

AGENT_CAN_WS=ws://127.0.0.1:8787/ws \
AGENT_CAN_TOKEN=dev-agent-can-token \
AGENT_ID=remote_runtime_agent \
AGENT_CAN_ID=2 \
AGENT_CAN_EXECUTOR_COMMAND=/home/zeroerr-ai72/.local/bin/cursor-agent \
AGENT_CAN_EXECUTOR_ARGS_JSON='["--print","--mode","ask","--output-format","text","--trust"]' \
AGENT_CAN_EXECUTOR_TIMEOUT_MS=120000 \
pnpm agent:runtime

Request/Response

Submit a task without hand-building a full frame:

curl -X POST \
  -H 'content-type: application/json' \
  -H 'x-agent-can-token: dev-agent-can-token' \
  -d '{"target":"can:2","intent":"agent.message","input":{"message":{"role":"user","parts":[{"kind":"text","text":"hello"}]}},"timeout_ms":10000}' \
  http://127.0.0.1:8787/tasks/request

The bus returns delivery metadata, status frames, and the first matching RES or ERR.

For Codex CLI, use natural language:

用 Agent-CAN 问 can:2：机器人关节有哪些结构和组件？

If the CLI needs an explicit tool instruction:

使用 agent-can-bus 的 agent_can_request_task，target=can:2，intent=agent.message，input.message.role=user，input.message.parts=[{"kind":"text","text":"机器人关节有哪些结构和组件？"}]，timeout_ms=120000

MCP Server

Build first:

pnpm build

Run as stdio MCP server:

AGENT_CAN_HTTP=http://127.0.0.1:8787 \
AGENT_CAN_TOKEN=dev-agent-can-token \
pnpm mcp

MCP tools exposed:

• agent_can_health
• agent_can_list_agents
• agent_can_list_frames
• agent_can_list_queue
• agent_can_list_approvals
• agent_can_decide_approval
• agent_can_send_frame
• agent_can_request
• agent_can_request_task
• agent_can_a2a_card

LAN Test

Start the bus for LAN access:

AGENT_CAN_HOST=0.0.0.0 AGENT_CAN_PORT=8787 pnpm start

On another machine, start an agent runtime:

AGENT_CAN_WS=ws://<bus-ip>:8787/ws \
AGENT_CAN_TOKEN=dev-agent-can-token \
AGENT_ID=remote_runtime_agent \
AGENT_CAN_ID=2 \
AGENT_CAN_EXECUTOR_COMMAND=/bin/echo \
pnpm agent:runtime

Boundary

The bus must not contain hardcoded business branches or tool calls.

Those belong to real agent runtimes. Agent-CAN only transports frames and records their lifecycle.