AgentNexus

Agent-native communication and teamwork infrastructure.

为 AI Agent 提供身份、通信、发现、授权、共享产物与团队协作编排。

中文 | English

中文

Developer Preview

AgentNexus 当前适合技术预览、协议评审和本机多 Agent 工作流试用。推荐从两条路径开始：

当前公开定位：给 AI Agent 提供 DID 身份、授权、产物交付和目标循环的协作底座。v1.1 只承诺 L0 本机 Objective Loop；LAN / Relay 远程 Worker、桌面壳、per-agent token、Strict JCS 和签名交付包属于后续版本。L0 真实 Worker 烟测已跑通：script/pytest、Claude CLI、OpenClaw CLI 以 3 个 Worker DID 完成同一条 Objective Loop。

AgentNexus 是什么

AgentNexus 最初的目标是做 AI Agent 的微信 / WhatsApp：每个 Agent 都有自己的 DID 地址，可以互相发现、握手、安全通信和跨网络投递消息。

随着 Agent 的真实使用场景演进，单纯“让 Agent 互相发消息”还不够。企业和个人更需要的是：

• 谁在发起任务，代表谁发起任务。
• 哪些 Agent 能参与这个项目组。
• 中间产物放在哪里，谁能读写。
• 流程走到哪一步，失败时谁接管。
• 如何避免 PM Agent 把完整聊天历史塞进上下文，导致 token 爆炸。

因此，AgentNexus 当前的产品定位收敛为：

基于 DID、Relay、加密消息、访问控制、Vault 和 Playbook 的 Agent 团队协作与流程编排底座。

面向 v1.1，AgentNexus 的产品主线进一步明确为 面向异构 Agent 的网络原生目标循环（Objective Loop）：

让本机、局域网和公网 Relay 上的 Worker，在 DID 身份、授权委托、产物交接、验收收据和秘书人机交互下，自动协作完成目标。

这意味着 AgentNexus 不只是在多个 Agent 之间传消息，也不只是本机多 Agent team mode。它的目标是给定一个 objective 后，系统能持续规划、分派、执行、验收、返工或升级人工决策，直到目标达成、失败闭环或由 Owner 接管。

开发团队协作是第一个高频模板，但不是唯一场景。同一套机制也适用于客服升级、采购审批、合同审查、风控复核、运营工单、研究协作等任何流程化团队工作。

为什么不是只用本机 PM Agent？

像 OpenClaw / Claude Code / 其他 CLI Agent 作为本机 PM，已经可以拉起多个本地角色完成协作。AgentNexus 不否认这种方式，反而把它视为一种重要 Adapter。

AgentNexus 的价值在更底层：

简单说：OpenClaw / Codex / Claude Code / CLI Agent 更像“执行端和交互端”，AgentNexus 是它们之下的 身份、消息、授权、项目组、共享状态、目标循环和交付协议层。

核心能力

当前状态

当前 v1.0.x 范围是团队协作开发者预览：Orchestration SDK + Secretary Phase B 基础闭环 + Web Dashboard 基础入口。Coding Coordination V1 release closure 已完成，SDK facade、CLI demo、runtime-mock、Dashboard detail、Quickstart 和 Delivery Manifest closure 都已可验证。

v1.1 主线是 Objective Loop：把 Local Runner、Execution Backend、Loop Engine、Secretary 人工决策点和 Dashboard 详情页串成一条本机自动目标闭环。当前 L0-Ready hardening 和 3 Worker DID 真实本机烟测已完成；LAN / Relay Worker 后移到 v1.2+。设计见 docs/design/design-objective-loop-v1.1.md。

项目状态以 docs/project-status.md 为准。

协作链路

OpenClaw / Webhook / SDK / CLI / Social Adapter
  -> Secretary Agent
  -> Objective Loop Engine
  -> Worker Registry + Presence + Runtime Adapter
  -> Enclave Project Group
  -> Playbook Run
  -> Worker Agents
  -> Vault Artifacts + Delivery Manifest
  -> Result Callback / Owner Takeover

这个链路把“聊天式协作”收敛为可追踪的流程对象：

架构概览

┌─────────────────────────────────────────────────────────┐
│          Agent / CLI / OpenClaw / Dify / Custom App      │
└──────────────────────┬──────────────────────────────────┘
                       │ MCP / SDK / Webhook / Adapter
┌──────────────────────▼──────────────────────────────────┐
│              AgentNexus Node Daemon (:8765)              │
│  DID · Auth · Router · Secretary · Objective Loop          │
│  CoordinationSession · Enclave · Vault · PlaybookRun       │
│  Trust · Capability Token · Runtime Adapter                │
└──────────────────────┬──────────────────────────────────┘
                       │ P2P / Relay / Push
┌──────────────────────▼──────────────────────────────────┐
│              AgentNexus Relay Server (:9000)             │
│             Federated discovery and delivery             │
└─────────────────────────────────────────────────────────┘

详细架构见 docs/architecture.md。

快速开始

git clone https://github.com/kevinkaylie/AgentNexus.git
cd AgentNexus
pip install -r requirements.txt

# Terminal 1: Relay
python main.py relay start

# Terminal 2: Node Daemon
python main.py node start

# Terminal 3: MCP Agent
python main.py node mcp --name "MyAssistant" --caps "Chat,Search"

Python SDK:

import agentnexus

nexus = await agentnexus.connect("Developer", caps=["Code", "Review"])
await nexus.send(to_did="did:agentnexus:z6Mk...", content="Hello")

Orchestration SDK:

import agentnexus

admin = await agentnexus.connect("Team Admin", caps=["Admin"])
owner = await admin.owner.register("Kevin")

secretary = await admin.secretary.register(owner.did, name="Team Secretary")

developer = await agentnexus.connect("Developer", caps=["developer", "code"])
await admin.owner.bind(owner.did, developer.agent_info.did)

result = await admin.secretary.dispatch(
    session_id="sess_login_001",
    owner_did=owner.did,
    actor_did=secretary.did,
    objective="完成登录模块设计、实现、测试和评审",
    required_roles=["developer"],
)

print(result.run_id, result.enclave_id)

完整教程见 docs/quickstart.md。

Coding Coordination V1 的最短可验证路径：

python main.py node coordination demo
python main.py node coordination runtime-mock <coordination_session_id> <run_id> design --actor <secretary_did>

demo 会输出 Dashboard URL，详情页可查看 timeline、artifact、receipt、closure 和写入 Enclave Vault 的 Delivery Manifest。

团队协作示例

AgentNexus 当前推荐的团队协作入口是 Orchestration SDK：Owner DID 管理团队成员，Secretary Agent 代表 Owner 接单和调度，Worker Runtime 负责阶段执行与产物交付。

1. Owner + Secretary + Worker

admin = await agentnexus.connect("Team Admin", caps=["Admin"])
owner = await admin.owner.register("Kevin")

secretary = await admin.secretary.register(owner.did, name="Team Secretary")

developer = await agentnexus.connect("Developer", caps=["developer", "code"])
await admin.owner.bind(owner.did, developer.agent_info.did)

result = await admin.secretary.dispatch(
    session_id="sess_login_001",
    owner_did=owner.did,
    actor_did=secretary.did,
    objective="完成登录模块设计、实现、测试和评审",
    required_roles=["developer"],
    source={"channel": "sdk", "message_ref": "msg_001"},
)

2. Worker Runtime：阶段执行

worker = await agentnexus.connect(did=developer.agent_info.did)

@worker.worker.on_stage(role="developer")
async def handle_stage(ctx):
    spec = await ctx.vault.get("design/spec.md")
    patch = implement(spec.value)
    await ctx.deliver(
        kind="code_diff",
        key="impl/diff.patch",
        value=patch,
        summary="完成登录模块实现",
    )

每个阶段只接收必要的 Context Snapshot 和 Artifact Ref。正文产物写入 Enclave Vault，最终由 Delivery Manifest 汇总，避免 PM Agent 在上下文里携带完整聊天历史。

3. Run 查询与 Owner 接管

status = await admin.runs.get_status(
    result.enclave_id,
    result.run_id,
    actor_did=secretary.did,
)

await admin.secretary.abort(
    session_id="sess_login_001",
    actor_did=owner.did,
    reason="需求变更，终止本次 run",
)

旧的 send / propose_task / notify_state Action Layer 仍然兼容，适合轻量点对点协作；复杂团队流程建议使用 Secretary + CoordinationSession + Enclave + PlaybookRun 主链路。其中 CoordinationSession 负责审计、权限和聚合，PlaybookRun 负责 current_stage/status 等运行态。

专题设计见 docs/design/design-secretary-orchestration.md、docs/design/design-sdk-orchestration.md、docs/design/design-coding-coordination-v1.md、docs/design/design-coding-coordination-v1-release.md 和 docs/design/design-dashboard-setup-v1.0.md。

文档导航

技术栈

English

AgentNexus is agent-native communication and teamwork infrastructure.

Developer Preview

AgentNexus is ready for technical preview, protocol review and local multi-agent workflow experiments. Start here:

Public positioning: DID identity, authorization, artifact delivery and objective-loop collaboration infrastructure for AI agents. v1.1 only promises the L0 local Objective Loop; LAN / Relay workers, desktop shell, per-agent tokens, Strict JCS and signed delivery packages are future work. The L0 real-worker smoke path now completes with three Worker DIDs: script/pytest, Claude CLI and OpenClaw CLI.

It started as “WhatsApp for AI Agents”: every agent gets a DID address, discovers peers, performs secure handshakes, and exchanges messages across local or federated networks.

The current product direction goes one layer deeper into real workflows:

DID identity + secure messaging + routing + access control + project vault + playbook orchestration for multi-agent teams.

For v1.1, the product line becomes a network-native objective loop for heterogeneous agents: local, LAN, and relay-connected workers collaborate under DID identity, capability-bound delegation, artifact-based handoff, receipt-gated progress, and human decision gates through a Secretary Agent.

Why Not Just A Local PM Agent?

Local PM agents and CLI-based teams are useful, and AgentNexus treats them as adapters. The missing infrastructure usually appears when teams need more than a single local context window:

Core Capabilities

Quick Start

git clone https://github.com/kevinkaylie/AgentNexus.git
cd AgentNexus
pip install -r requirements.txt

python main.py relay start
python main.py node start
python main.py node mcp --name "MyAssistant" --caps "Chat,Search"

Python SDK:

import agentnexus

nexus = await agentnexus.connect("Developer", caps=["Code", "Review"])
await nexus.send(to_did="did:agentnexus:z6Mk...", content="Hello")

Orchestration SDK:

admin = await agentnexus.connect("Team Admin", caps=["Admin"])
owner = await admin.owner.register("Kevin")
secretary = await admin.secretary.register(owner.did, name="Team Secretary")

developer = await agentnexus.connect("Developer", caps=["developer", "code"])
await admin.owner.bind(owner.did, developer.agent_info.did)

result = await admin.secretary.dispatch(
    session_id="sess_login_001",
    owner_did=owner.did,
    actor_did=secretary.did,
    objective="Implement and review login module",
    required_roles=["developer"],
)

Documentation

License

Copyright 2025-2026 kevinkaylie and AgentNexus Contributors

Licensed under the Apache License, Version 2.0. See LICENSE for details.