Agent 与 A2A API¶
Agent Product API 有两类边界：A2A 接口提供相对稳定的发现与运行入口；Agent 管理、 Builder、Manifest、Provider、任务、自动化、通道、记忆、技能和工具资源目前通过工作区 资源代理路由暴露，尚未形成统一、稳定的高层请求与响应契约。
发现 Agent¶
GET /newmoi/agents/card
Agent Card 描述部署环境开放的 Agent 身份与 A2A 能力。构造客户端前应先读取 Card； 支持的消息 Part、任务行为、流式能力、补充输入和扩展项都应以返回内容为准，不能自行 假设。
调用者仍需携带 X-Workspace-ID 并通过工作区权限校验。从一个工作区取得的 Agent
code 或 Card，不能授权调用者在另一个工作区使用同名 Agent。
发送 A2A 请求¶
POST /newmoi/agents/a2a
这是产品 A2A 运行入口。请求应使用部署契约定义的 A2A method 与 payload。产品客户端 覆盖的核心任务流程包括：发送消息、读取任务状态、取消任务，以及在任务请求补充信息时 提交输入。
每个请求都应：
生成并保留调用方 request ID；
协议要求时使用调用方生成的 message ID；
保存返回的 task ID 与 turn ID；
把文本、数据、文件和 Artifact 保留为有类型的协议 Part；
把“等待补充输入”视为非终态；
只在契约定义的任务终态停止轮询或流式读取。
传输超时不能证明 Agent 未创建任务。再次发送相同 Prompt 前，先用 task ID 或 request ID 查询。取消请求也可能是异步操作，只有任务状态确认取消后才算完成。
流与 Artifact¶
部署启用 Streaming 时，应按顺序增量解析事件。状态更新不是答案 Part；Artifact 更新 会根据元数据覆盖或追加既有内容。不能把全部事件直接拼成纯文本，也不能丢弃后续调用 需要的 Artifact ID。
Agent 输出可能包含外部工具结果或链接，应作为不可信应用数据处理：验证 URL 与文件 类型，不要自动执行返回的命令。
Agent 管理边界¶
已注册的工作区路由族包括：
/newmoi/workspaces/:id/agents
/newmoi/workspaces/:id/agent-builder
/newmoi/workspaces/:id/agent-runtime
/newmoi/workspaces/:id/agent-runtime-manifests
/newmoi/workspaces/:id/agent-runtime-providers
/newmoi/workspaces/:id/agent-runtime-tasks
相关资源族还包括自动化、通道、记忆、技能与工具。这些接口当前属于通用的 backend-to-core 代理。不要通过抓取界面请求并猜测 CRUD 字段来建立长期集成；应使用 目标部署发布的 OpenAPI，并在自动化资源生命周期前确认已有稳定的产品 Schema。
外部自动化或通道应绑定不可变且已验证的 Agent 版本，而不是可变草稿。排查未触发问题 前，先核对凭据、回调签名、时区、目标权限与最近一次部署结果。
Agent 使用的知识来源见知识库与 Explore；模型供给见 模型与 Provider。