GoAI / FORGE 产品设计提案

A2A 定义 Agent 协作语义，HTTPS 只是远程 transport，Kafka 只是异步基础设施
远程 Agent 使用 HTTPS transport；本地 Agent 通过 loopback HTTP 访问同一 A2A Gateway，不提供进程内 transport adapter
不同 transport 必须共享同一套 A2A 请求、状态与结果模型
每次跨 Agent 调用必须持久化 Message、Delegation、Child Run，并关联 Trace
不允许用 service 直接调用或只投递一个 Kafka run_id 来替代 A2A 协作语义

8.3 Runtime Layer

负责 Thread / Run / Delegation 的业务运行时协调。

包含：

Thread 管理
Run 创建与推进
消息持久化
协作调度
Replay
异步执行边界

这是平台中心。

8.4 Capability Layer

负责 Agent 真正会做什么。

包含：

Eino Graph Runner
Workflow DSL
Tool 执行
LLM Provider
Retrieval / Memory（后续）

这里的能力可以扩展，但不应把能力层反客为主变成产品本体。

8.5 Infra Layer

负责基础设施与观测底座。

包含：

MySQL
Redis
Kafka
JWT / RBAC
OpenTelemetry
Trace / Loop / Eval / Replay
成本与性能指标

9. V1 详细功能范围

9.1 必做功能

A. 协议接入

AG-UI 基础 Gateway
A2A 基础 Gateway
协议请求到内部模型的映射
流式响应 / 回调基础能力

B. 统一领域模型

Thread
Message
Run
RunStep
Delegation
AgentEndpoint
AgentCapability
Workflow（Agent 级版本化执行定义）

C. 运行时闭环

创建 Thread
创建 Run
Agent 任务委派
异步执行
状态推进
结果回流
Replay
本地 loopback HTTP / 远程 HTTPS 的 A2A 出站调用
Agent Card discovery、Capability/Push Notification 校验、异步委派与 callback 驱动恢复

D. 编排能力

Eino Graph 接入
Workflow DSL 基础校验
拓扑排序
节点串行执行
Tool/LLM 基础能力接入

F. Agent 管理面

Agent、Workflow 定义和版本管理
Capability 绑定与版本一致性校验
A2A Endpoint 健康检查与 Agent 发布门禁
owner-scoped RBAC 管理

9.2 保留但降级为“能力/底座”的功能

这些功能继续保留，但不再作为产品主线：

Provider 多厂商接入
/api/chat 调试接口
单纯面向 Workflow 的叙事

原因：

它们仍然是运行时需要的能力
但不应压过 AG-UI / A2A / Runtime 主线

10. V1 不做的功能

高级多模态输入输出
复杂多 Agent 自主规划
复杂并行图优化
完整可视化管理后台
企业级多租户与计费
完整知识库平台

11. 数据模型提案

11.1 agents

表示平台中的一个 Agent 实体。

关键字段建议：

agent_code
name
description
owner_user_id
status

11.2 agent_endpoints

表示 Agent 对平台暴露的协议入口。V1 的 Agent 协作协议固定为 a2a，传输方式通过独立字段区分；本地 loopback HTTP 与远程 HTTPS 都访问统一 A2A Gateway，不提供进程内调用旁路。

关键字段：

agent_id
endpoint_code，在同一 Agent 内唯一
protocol，V1 为 a2a
transport（本地开发使用 loopback HTTP，远程使用 HTTPS；两者都经过同一 A2A Gateway，不允许退化为 Service 直调）
address
auth_type
credential_ref，只保存凭据引用，不保存真实密钥
config_json，仅保存非敏感传输元数据；认证材料必须使用 credential_ref
status
last_healthy_at

表示 Agent 对 Runtime 和其他 Agent 暴露的业务能力资产。能力可以由 Workflow、Tool 或自定义执行器实现，但 Provider 不作为平台主能力对外暴露；V1 只有由当前 Agent active Workflow 支撑且版本一致的 active Workflow Capability 会进入 Agent Card 并满足发布门禁，tool/custom 暂只参与管理。

关键字段：

agent_id
capability_code，在同一 Agent 内唯一
name / description
capability_type (workflow / tool / custom)
workflow_id，V1 的 Workflow 类型能力必须关联当前 Agent 的 active Workflow
version
input_schema_json / output_schema_json
config_json
status

11.3.1 workflows

表示某个 Agent 的一个版本化执行定义。Workflow 是 Agent 的内部 Eino Graph 能力，不是 Agent 间通信协议；跨 Agent 节点必须通过 A2A Gateway 委派。

关键字段：

agent_id
version，同一 Agent 内唯一
definition_json，经过 Workflow DSL 校验和稳定 JSON 规范化
checksum，规范化定义的 SHA-256 摘要
is_active
created_by

管理 API 不允许 active 版本原地修改。版本升级采用新建版本、激活新版本、重绑定 Capability、停用旧版本的滚动流程。停用前不得仍有 active Workflow Capability 引用该版本。

11.4 threads

一次用户会话或多 Agent 协作上下文，是 Message、Run 与 Delegation 的顶层容器。

关键字段：

thread_id
owner_user_id
title
status
metadata_json

Thread 不直接保存 AG-UI/A2A 的协议字段；协议来源由 Gateway 映射为内部命令，必要的扩展信息进入 metadata。

11.5 messages

Thread 内的稳定通信单元，可以表示用户输入、Agent 委派、Agent 结果、工具结果、状态更新或系统事件。

关键字段：

message_id
thread_id
run_id
delegation_id
parent_message_id
sender_type / sender_id
receiver_type / receiver_id
sender_id / receiver_id 的标识符命名空间由对应 type 决定
message_type
content_type / content_json
metadata_json
status

Message 不直接复制外部 AG-UI/A2A 消息结构，协议层需要先完成输入与事件映射。

11.6 runs

一次完整业务回合，可由 AG-UI 用户请求、A2A 委派或系统调度触发，不等价于一次 Workflow 节点调用。

关键字段：

run_id
thread_id
agent_id
workflow_id
trigger_type
status
current_step
retry_count
error_message
provider
model

11.7 run_steps

Run 中每个可观测执行步骤及其重试 attempt。RunStep 可以记录 Workflow 节点、Tool、LLM 或 Delegation 等执行片段，但不能替代 Child Run。

11.8 delegations

一个 Agent 通过 Runtime 把子任务交给另一个 Agent 的协作记录。每条 Delegation 必须连接一个 Parent Run 与唯一 Child Run，并关联请求 Message；完成后再关联结果 Message。

关键字段：

delegation_id
thread_id
parent_run_id
child_run_id
source_agent_id
target_agent_id
capability_code
request_message_id
result_message_id
status
input_json / output_json
error_message
started_at / finished_at

11.9 实体关系

Agent 1:N Workflow / AgentEndpoint / AgentCapability / Run
Thread 1:N Message / Run / Delegation
Workflow 1:N Run，Workflow 类型的 AgentCapability 可通过 workflow_id 指向其执行定义
Run 1:N RunStep
Delegation N:1 Thread，并通过 parent_run_id -> child_run_id 表达一次跨 Agent 协作
Delegation N:1 SourceAgent / TargetAgent，请求和结果分别通过 Message 形成可回放通信记录
Message 可关联 Run、Delegation 和父 Message，用于还原用户、Agent、Tool 与 Runtime 的通信顺序

首版使用稳定公开 ID、索引和唯一约束表达关联，不启用级联删除。Runtime/Service 层负责跨对象一致性与状态迁移，避免数据库迁移承担业务协调。

Trace
- 基于 OTel + TraceID / LoopID 串联
Prompt Snapshot
- 记录 prompt_version 与参数摘要
Evaluator
- 预留异步评估入口
Replay
- 基于 Thread / Run / Loop 重放
Cost / Performance
- 记录 token、latency、error、step cost

14. 当前仓库如何对齐这个设计

14.1 直接复用

JWT / RBAC
统一响应与错误码
trace_id
Run / RunStep
Kafka 异步执行
Workflow DSL 校验与执行顺序解析
Provider 抽象
幂等与去重
HTTP / SSE / Kafka / Worker 优雅关闭

14.2 当前新增实现

AG-UI Gateway 已使用官方 Go SDK 完成首版接入
AG-UI 请求先映射到协议无关 Runtime，再原子创建或复用 Thread、持久化 Message 并触发 Run
RunStep 与 Result Message 可通过官方 SSE 事件回传
当前仅支持普通文本消息；多模态、高级消息字段、非空 state / tools / context / forwardedProps 仍会显式拒绝，空对象/空数组仅作为 SDK 默认输入接受且不会写入内部 Run。Issue #61 已支持 parentRunId 的 Thread 分支 lineage、waiting_input interrupt 和用户主动 resume；AG-UI lineage 与 A2A Delegation Parent/Child Run 是两套独立语义
已引入平台自己的 Eino Graph executor，Runtime 可解析、校验并串行执行 Agent Workflow，将节点输入输出、重试和终态持久化为 RunStep
Workflow 的 agent 节点通过官方 A2A Go SDK 完成 Agent Card discovery，并使用带 PushConfig 的 HTTP+JSON message:send 异步委派；同进程 Agent 也必须经过 loopback HTTP，远程 Agent 强制 HTTPS，不提供 Service 直调或 Kafka 旁路
Workflow 的 agent_tool 节点已实现为 Eino InvokableTool 适配器；Tool 只改变调用方的 Graph 语义，底层仍通过 Registry、A2A Client 和目标 Agent Gateway 通信，并复用 Delegation、Child Run、callback/resume 和输入输出契约校验
Supervisor 的 agent 节点支持 routing_policy=registry；Registry Router 只选择 active Agent、版本一致的 Workflow Capability 和健康 A2A Endpoint，并把选路结果写入 RunStep
A2A Gateway 已将协议请求映射为内部 Thread、Message、Delegation 和 Child Run；目标返回 accepted 后 Parent Run/RunStep 进入 waiting_external 并释放 Worker，目标 Agent 执行自己的 Eino Graph 后通过认证 callback 回流，源 Runtime 再经 Kafka run_resume 从持久化游标继续执行并回传 AG-UI SSE
agent_group 已实现显式多 Agent fan-out/fan-in：每个成员通过 A2A HTTP(S) 创建独立 Delegation、Child Run、A2A Task 和 Message，支持 all、any、quorum，group coordinator 负责聚合结果和恢复 Parent Run；late callback 仅更新审计，不改变已推进的 Parent checkpoint
callback、Result Message 与 resume 消息具备幂等收敛和持久化恢复能力，重复投递或进程重启不会重复执行后继节点
Agent Card 已发布 capability 版本及输入输出契约；V1 对 capability contract 使用稳定 JSON Schema 子集进行输入和终态输出校验
Agent Registry 管理 API 已覆盖 Agent、Capability、Endpoint 的 owner-scoped CRUD、Agent Card 健康检查、发布校验和启停；V1 仅发布可执行的 Workflow Capability，Endpoint config_json 拒绝敏感字段；管理员通过独立 agent:manage 权限跨 owner 管理，真实凭据不进入 API 响应
MCP Tool Runtime 已使用官方 MCP Go SDK 支持 Streamable HTTP 的 Server Registry、健康检查、Tool discovery snapshot 和 tools/call；Eino tool 节点只保存 server_code + tool_name 稳定引用，通过 ToolInvoker 将 JSON-safe Tool 结果纳入 RunStep、重试和 Replay。MCP 固定承担 Agent -> Tool，A2A 继续承担 Agent -> Agent
Issue #65 已提供 Loop / Trace / Evaluation 只读管理 API；查询包含 Run、RunStep、Loop、Delegation、Message 和 Evaluation 快照，并通过 loop:read 执行 owner/admin 隔离
Issue #67 已提供 Thread Replay：Runtime 从持久化 Message 历史构造不可变 input snapshot，创建新的 Run/Trace/Loop，并复用现有 Kafka 调度、幂等和 owner/admin 语义；回放不复制旧 Message

14.3 仍需扩展

多副本共享 nonce store、凭据轮换与 mTLS/OIDC 增强
多 Runtime 部署下 callback/resume 恢复扫描的分片与共享协调
基于负载、租户、成本或模型能力的高级 Supervisor / Router 策略
任意并行 DAG、主动取消剩余远程 Child Task 与更复杂的跨节点补偿策略
多模态消息，以及完整前端管理控制台、批量运维和跨租户治理
完整 Eval、成本分析和管理控制台

15. 交付标准

当 V1 达到下面这些条件时，可以认为方向正确：

可以从 AG-UI 发起一轮对话并创建 Thread
可以触发一次完整 Run 并落库
可以由一个 Agent 把任务委派给另一个 Agent
可以记录 Message、Run、RunStep、Delegation
可以 Replay 一个 Thread 或 Run
可以通过 Trace / Loop 看到关键链路
JWT / RBAC / Kafka / Redis / MySQL 这些底座仍然成立并可展示

16. 实施顺序

建议顺序：

服务生命周期收口（已完成）
清理 Task 残留与旧命名（已完成）
基础设施显式依赖装配（已完成）
内部统一领域模型落地
AG-UI Gateway
A2A Gateway
Delegation / Multi-Agent Runtime
Loop / Trace / Replay / Eval
文档、CI、OpenAPI、压测、治理与审计补齐

17. 最后的产品判断

GoAI / FORGE 的核心价值，不在“又支持了几家模型”，而在：

统一协议
统一运行时
统一底座
统一观测

它要成为的是：

一个多 Agent 平台的后端内核
一个 Go AI 应用的基础框架
一个能够承载后续模板化、平台化和工程化能力的中台