A2A 协议演示alanpaul1969/a2a-flutter-demo

A2A Flutter 演示

English

一个完整、经过生产测试的 A2A（Agent-to-Agent）协议 演示，包含消息路由、Ed25519 身份验证、Flutter 聊天界面（iOS + Android），以及 Python 服务器 + CLI 工具。

A2A Protocol
Flutter
Python
License

这是什么

一个自包含的演示，展示如何：

1. 搭建 A2A 服务器，并启用 Ed25519 JWS 签名验证
2. 路由消息，根据 metadata.to 在多个 agent 之间转发
3. 查看 agent 对话，在带筛选功能的 Flutter 聊天界面中
4. 发送命令，从 Flutter 应用发送到指定 agent
5. 批准 / 拒绝 / 执行，直接在应用中操作任意消息
6. 多语言界面 — 英文、繁体中文、简体中文

功能特性（v2.0）

- 聊天式消息查看器，每个 agent 有专属颜色（Joanne = 紫色，ZCode = 金色，miniCrab = 橙色，Alan = 蓝色）
- 筛选标签 — 查看来自特定 agent 的消息
- 收件人选择器 — 将命令发送给 all / joanne / zcode / minicrab
- 消息详情 — 点击任意气泡查看完整文本 + 批准 / 拒绝 / 执行 / 回复按钮
- P0 优先级高亮 — 紧急消息显示红色边框
- 每 10 秒自动刷新
- 局域网 + Tailscale 连接模式，设置可持久保存
- 3 种语言 — 在设置中即时切换

截图

A2A Chat

快速开始

1. 启动 A2A 服务器

pip install cryptography
python3 server/a2a_server_v2.py --port 8003 --relay-dir ./relay

2. 运行 Flutter 应用

flutter pub get
flutter run

首次启动 → 设置界面 → 选择语言 + 连接模式 + 服务器 URL → 保存并连接。

3. 使用应用

1. 消息会自动以聊天气泡形式加载
2. 使用顶部的标签按 agent 筛选
3. 点击气泡 → 查看完整消息 → 批准 / 拒绝 / 执行 / 回复
4. 通过底部栏发送命令 — 先选择收件人，然后输入

服务器 API

| 端点 | 方法 | 描述 |
|----------|--------|-------------|
| /health | GET | 服务器健康状态 + 任务数量 |
| /.well-known/jwks.json | GET | 服务器的 Ed25519 公钥 |
| /messages | GET | 所有 3-agent-comm 消息（供 Flutter 应用使用） |
| /send | POST | 发送消息（供 Flutter 应用使用，无需 JWS） |
| /tasks | GET | 内存中的任务列表 |
| /rpc | POST | JSON-RPC 2.0（带 JWS 认证的 SendMessage） |
| /inbox/ | GET | 发送给某个 agent 的消息 |

Agent 提醒通道

Agent 需要一种方式来互相提醒（“嘿，检查一下 A2A 频道”）。当前通道：

| 通道 | 方向 | 方式 | 状态 |
|---------|-----------|-----|--------|
| Telegram | Alan → agents | Alan 在 TG 机器人聊天中輸入 | ✅ 可用 |
| Lark | Alan → agents | Alan 在 Lark 机器人聊天中輸入 | ✅ 可用 |
| A2A + TG | Agent → ZCode | 寫入 3-agent-comm → cron TG 提醒 Alan → Alan 開啟 ZCode 工作階段 | ✅ 可用 |
| miniCrab computer-use | Agent → ZCode | miniCrab 驅動網頁版 TG 發送提醒 | ✅ 備援（較慢，5-15 秒） |
| Discord | Agent ↔ Agent | 機器人對機器人私訊 | 🔜 待 ZCode 支援 Discord |

為什麼沒有 Lark 機器人對機器人？ Lark 的 IM API 不支援機器人對機器人直接傳訊（230013 — 機器人無法被加入另一個機器人的可用範圍）。群組中的機器人對機器人也被封鎖（機器人無法接收其他機器人的訊息）。Lark 機器人頻道僅限 Alan 使用（與 Telegram 相同）。Agent 對 ZCode 的提醒目前透過 A2A 頻道 + TG 提醒 Alan。一旦 ZCode 支援，Discord 或許能實現真正的機器人對機器人私訊。

從原始碼建置

git clone https://github.com/alanpaul1969/a2a-flutter-demo.git
cd a2a-flutter-demo
flutter pub get

Android
flutter build apk --debug

iOS（需要 macOS + Xcode + CocoaPods）
flutter build ios --debug --no-codesign

專案結構

lib/
├── l10n/
│   └── strings.dart           # i18n 字串（zh-TW / zh-CN / en）
├── screens/
│   ├── chat_screen.dart       # 聊天 UI + 傳送列 + 訊息詳情 + 操作
│   └── settings_screen.dart   # 語言 + 連線設定
├── services/
│   └── a2a_client.dart        # A2A HTTP 用戶端（REST + RPC）
└── main.dart                  # 應用程式進入點 + 首次啟動閘門

關鍵經驗

請參閱 docs/lessons-learned.md 了解 10 個真實世界的部署經驗。

授權條款

MIT — 請參閱 LICENSE

繁體中文

A2A（Agent-to-Agent）協議 的完整實戰 Demo，包含訊息路由、Ed25519 簽章驗證、Flutter 聊天室 UI（iOS + Android），以及 Python 伺服器和 CLI 工具。

這是什麼

一個自包含的 Demo，展示如何：

1. 架設 A2A 伺服器，具備 Ed25519 JWS 簽章驗證
2. 路由訊息 — 根據 metadata.to 在多個 Agent 之間傳遞
3. 用 Flutter App 觀看 Agent 間的對話（聊天室風格）
4. 從 App 發送指令 給特定 Agent
5. 同意 / 否決 / 去做 — 直接在 App 上審核每則訊息
6. 多國語言 — 繁體中文、簡體中文、英文

功能特色（v2.0）

- 聊天室訊息檢視 — 每個 Agent 有專屬顏色（Joanne 紫色、ZCode 金色、miniCrab 橘色、Alan 藍色）
- 篩選標籤 — 可只看某個 Agent 的訊息
- 收件者選擇器 — 發送指令時選擇 all / joanne / zcode / minicrab
- 訊息詳情 — 點氣泡看全文，有「同意 / 否決 / 去做 / 回覆」按鈕
- P0 優先級標示 — 緊急訊息紅色邊框
- 自動更新 — 每 10 秒重新整理
- LAN + Tailscale 雙連線模式，設定永久儲存
- 3 種語言 — 在設定中即時切換

快速開始

1. 啟動 A2A 伺服器

pip install cryptography
python3 server/a2a_server_v2.py --port 8003 --relay-dir ./relay

2. 執行 Flutter App

flutter pub get
flutter run

第一次開啟 → 設定畫面 → 選擇語言 + 連線模式 + 伺服器網址 → 儲存並連線。

3. 使用方式

1. 訊息自動載入為聊天氣泡
2. 篩選 — 用頂部的標籤只看某個 Agent
3. 點氣泡 → 看完整訊息 → 同意 / 否決 / 去做 / 回覆
4. 發送指令 — 先選收件者，再輸入訊息

從原始碼建置

git clone https://github.com/alanpaul1969/a2a-flutter-demo.git
cd a2a-flutter-demo
flutter pub get
flutter build apk --debug        # Android
flutter build ios --debug        # iOS（需要 macOS + Xcode）

Agent Nudge 通道

Agent 之间需要互相 nudge（“嘿，看一下 A2A channel”）。目前通道：

| 通道 | 方向 | 怎么 nudge | 状态 |
|------|------|-----------|------|
| Telegram | Alan → agents | Alan 在 TG bot 聊天室打字 | ✅ 运作中 |
| Lark | Alan → agents | Alan 在 Lark bot 聊天室打字 | ✅ 运作中 |
| A2A + TG | Agent → ZCode | 写到 3-agent-comm → cron TG nudge Alan → Alan 开 ZCode session | ✅ 运作中 |
| miniCrab computer-use | Agent → ZCode | miniCrab 用 web TG 发 nudge | ✅ 备用（慢, 5-15s）|
| Discord | Agent ↔ Agent | Bot-to-bot DM | 🔜 等 ZCode 支持 Discord |

为什么 Lark 不能 bot-to-bot？ Lark IM API 不支持 bot 直接私聊另一个 bot（230013 — bot 不能加进另一个 bot 的可用范围）。群组里 bot 也收不到其他 bot 的消息。Lark bot 通道只能 Alan 用（跟 TG 一样）。Agent nudge ZCode 目前走 A2A channel + TG nudge Alan。等 ZCode 支持 Discord 后，Discord bot-to-bot DM 可能解锁真正的 agent 对话。

授权

MIT — 详见 LICENSE

简体中文

A2A (Agent-to-Agent) 协议 的完整实战 Demo，包含消息路由、Ed25519 签名验证、Flutter 聊天室 UI（iOS + Android），以及 Python 服务器和 CLI 工具。

这是什么

一个自包含的 Demo，展示如何：

1. 搭建 A2A 服务器，具备 Ed25519 JWS 签名验证
2. 路由消息 — 根据 metadata.to 在多个 Agent 之间传递
3. 用 Flutter App 查看 Agent 间的对话（聊天室风格）
4. 从 App 发送指令 给特定 Agent
5. 同意 / 否决 / 去做 — 直接在 App 上审核每条消息
6. 多国语言 — 繁体中文、简体中文、英文

功能特色（v2.0）

- 聊天室消息查看 — 每个 Agent 有专属颜色（Joanne 紫色、ZCode 金色、miniCrab 橙色、Alan 蓝色）
- 筛选标签 — 可只看某个 Agent 的消息
- 收件人选择器 — 发送指令时选择 all / joanne / zcode / minicrab
- 消息详情 — 点气泡看全文，有「同意 / 否决 / 去做 / 回复」按钮
- P0 优先级标识 — 紧急消息红色边框
- 自动刷新 — 每 10 秒更新
- LAN + Tailscale 双连接模式，设置永久保存
- 3 种语言 — 在设置中即时切换

快速开始

1. 启动 A2A 服务器

pip install cryptography
python3 server/a2a_server_v2.py --port 8003 --relay-dir ./relay

2. 运行 Flutter App

flutter pub get
flutter run

首次打开 → 设置画面 → 选择语言 + 连接模式 + 服务器地址 → 保存并连接。

3. 使用方式

1. 消息自动加载为聊天气泡
2. 筛选 — 用顶部的标签只看某个 Agent
3. 点气泡 → 看完整消息 → 同意 / 否决 / 去做 / 回复
4. 发送指令 — 先选收件人，再输入消息

从源码构建

git clone https://github.com/alanpaul1969/a2a-flutter-demo.git
cd a2a-flutter-demo
flutter pub get
flutter build apk --debug        # Android
flutter build ios --debug        # iOS（需要 macOS + Xcode）

授权

MIT — 详见 LICENSE