Agent 开发规范

Version: 1.1
Status: Stable for Agents Marketplace

本文面向 Agent 作者：说明如何用 Python / Node.js 与主流框架（LangGraph、OpenAI Agents SDK 等）打包可上架的 zip，以及市场强制的 标准输入 / 输出 约定。

相关文档：

• agent-package-spec.md — 包文件清单与校验规则
• agent-io-spec.md — 请求 / 响应信封
• schemas/ — 机器可读 Schema

站点入口：菜单 Spec → /spec。完整范例包：examples/meeting-notes-agent。

1. 一句话原则

1. 一个 zip = 一份可安装、可运行的 Agent 软件包。
2. 必选：AGENT.md（安装与运行）、Soul.md（特性 / 人格）、标准 I/O Schema。
3. 其余一律可选（agent.yaml、源码、依赖锁文件、examples、tools…）。
4. 所有调用必须走统一 I/O 信封；每个 Agent 必须声明是否支持 多模态输入。

2. Zip 包需要什么

2.1 推荐布局

{slug}/                          # 或 zip 根目录直出（无顶层文件夹）
  AGENT.md                       # 必选：安装 / 运行说明 + frontmatter
  Soul.md                        # 必选：Agent 特性 / 人格 / 行为边界
  schemas/
    input.schema.json            # 必选：业务 input JSON Schema
    output.schema.json           # 必选：业务 output JSON Schema
  agent.yaml                     # 可选：机器可读 Manifest（推荐提供）
  src/ 或 app/                   # 可选：Python / Node.js 源码
  pyproject.toml / requirements.txt / package.json   # 可选：依赖声明
  examples/                      # 可选：request.json / response.json
  tools/ assets/ prompts/        # 可选

2.2 必选 vs 可选

市场上传校验：缺少任一必选文件会拒绝发布。

3. AGENT.md（必选）

3.1 位置

必须在 包根目录：

• AGENT.md
• 或 {slug}/AGENT.md（仅允许一层顶层目录）

3.2 Frontmatter（最少字段）

---
name: code-reviewer-agent
description: Review diffs and report high-confidence defects.
version: 1.2.0
language: python                 # python | nodejs
framework: langgraph             # langgraph | openai-agents | langchain | custom
multimodal: false                # 是否支持多模态输入（必填）
---

3.3 正文必须写清

1. Install（安装） — 依赖、虚拟环境 / npm install、环境变量（如 OPENAI_API_KEY）
2. Run（运行） — 启动命令、入口模块、如何接收标准请求信封
3. I/O 摘要 — 指向 schemas/，并写明 multimodal
4. （可选）配置、故障排查、许可证

示例骨架：

# Code Reviewer Agent

## Install

\`\`\`bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export OPENAI_API_KEY=...
\`\`\`

## Run

\`\`\`bash
python -m src.main --request examples/request.json
\`\`\`

Agent 从 stdin / 文件读取 **标准请求信封**，向 stdout 写出 **标准响应信封**。

## Input / Output

- multimodal: false
- schemas: `schemas/input.schema.json`, `schemas/output.schema.json`

4. Soul.md（必选）

定义 Agent 的 特性描述：人格、语气、价值观、禁止事项、协作偏好。
宿主 / 编排器可在运行前加载，用于 system prompt 或人格层。

建议结构：

# Soul

## Identity
简洁说明「我是谁、擅长什么」。

## Voice
语气、措辞偏好（例如：直接、缺陷优先、少客套）。

## Principles
1. …
2. …

## Boundaries
- 不做的事
- 需要用户确认的事

Soul.md 可带或不带 YAML frontmatter；内容以可读 Markdown 为主。

5. 支持的开发框架与语言

市场 不绑定单一运行时，只要包能按标准 I/O 被调用即可。当前明确支持作者使用：

实现约定（推荐）：

1. 提供一个 CLI 或 HTTP handler，读取 请求信封 JSON，写出 响应信封 JSON。
2. 业务 input / output 用包内 Schema 校验。
3. 多模态：multimodal: true 时，请求可带 attachments（见 I/O 规范）；为 false 时宿主不得传入非文本附件。

6. 标准输入 / 输出（所有 Agent 强制）

详见 agent-io-spec.md。

要点：

• 外层信封全市场统一：specVersion、requestId、agent、input / status+output。
• 业务字段只放在 input / output，由本包 Schema 约束。
• 必须在 AGENT.md frontmatter（或 agent.yaml）声明 multimodal。
• multimodal: true：允许 attachments[]（image / audio / video / file）。
• multimodal: false：仅文本（及 Schema 内声明的结构化字段）；出现附件应返回 INVALID_INPUT。

7. 可选文件说明

若省略 agent.yaml，市场默认：

• schemas/input.schema.json、schemas/output.schema.json
• name / description / multimodal 取自 AGENT.md frontmatter

8. 发布前自检清单

• zip 内可找到根级 AGENT.md 与同级 Soul.md
• AGENT.md 含 Install / Run，且 frontmatter 含 multimodal
• schemas/input.schema.json 与 schemas/output.schema.json 合法
• （若有）agent.yaml 的 name 与 AGENT.md 一致
• （若有）examples/*.json 符合 I/O 信封
• 本地用样例请求跑通一次端到端

9. 版本与兼容

• 包规范与 I/O 信封当前主版本：1.x（文档 specVersion: "1.0" / 开发规范 1.1 为文档修订）。
• 破坏性变更将提升主版本；新增可选字段保持兼容。
• 市场上架后，同 slug + 同 SemVer 不可重复覆盖。