← Docs/

§ API 参考

POST /v1/teams/v2/chat · AI Agent Teams (6 协作模式)

把 N 个 PMM-8+ 人格 (agent) 组成团队, 围绕一个议题协作产出. 6 种协作模式覆盖 concurrent / sequential / debate / red-blue / pipeline / auto. 输出 SSE 流, 跟 webapp /teams 完全同源 — 同一 conversation_id 可在 webapp 查看历史.

01

端点

Method
POST
Path
/v1/teams/v2/chat
Auth
Authorization: Bearer hipmm_sk_...
Plan
Pro / Max / Enterprise (Free / Starter 不支持)
Cost
动态 — debate 1 轮 4 agent ≈ 25u · 2 轮 ≈ 40u · 4 轮 ≈ 80u+ (按 token 阶梯)
Response
text/event-stream (SSE)
Timeout
3-15 min, 跟模式 + 轮数 + agent 数挂钩. nginx proxy_read_timeout 已设 1800s.

同步到 webapp

通过 API 创的 conversation 自动出现在 webapp /teams 左侧会话列表 (同 user 下). conversation_id 由响应首个 conversation 事件返回.
02

6 协作模式

mode说明适用场景
concurrent全员并发独立发言, 互不参考多视角扫描 / 头脑风暴
sequential顺序接力, 后者看前者发言, 可承接 / 反驳渐进推理 / 迭代精化
debate独立陈述 → N 轮交叉质询 (含 MECE 中场裁定) → 麦肯锡级综合报告决策博弈 / 选择题深度分析
red-blue前半红方进攻, 后半蓝方防守压力测试 / 找漏洞
pipeline4 阶段决策流水线: 拆解 → 选项 → 风险 → 推荐结构化决策
autolead 看议题自决模式 + agent 组合不确定选啥时用
03

请求体

application/json

{
  "agents": [
    { "id": "pm",  "name": "产品经理", "code": "O-A-H-X-ED-AR-VE-LT", "role": "用户痛点+商业可行性" },
    { "id": "eng", "name": "工程师",   "code": "I-C-L-B-ID-PR-SE-ST", "role": "技术复杂度+维护成本" },
    { "id": "mkt", "name": "市场",     "code": "O-A-L-X-ED-AR-VE-LT", "role": "用户增长+渠道" },
    { "id": "usr", "name": "终端用户", "code": "I-C-H-X-ID-PR-VE-ST", "role": "实际使用感受" }
  ],
  "mode": "debate",
  "rounds": 2,
  "prompt": "PMM8 试用免费 3 天 vs 永久免费 — 哪个更利于扩张?",
  "user_name": "Leo",
  "conversation_id": null,
  "active_agent_ids": null
}
字段类型必填说明
agentsarray<TeamAgentSpec>1-10 个 agent. Pro 6, Max+Ent 10 (超管可 override)
agents[].idstring≤32 字 / [a-zA-Z0-9_-]
agents[].namestring≤24 字 显示名
agents[].codestringPMM-8+ 8 维度代号 (见 /docs/pmm8)
agents[].rolestring团队里的角色描述 ≤400 字
modeenumconcurrent / sequential / debate / red-blue / pipeline / auto
promptstring议题 1-4000 字
roundsintdebate 模式 1-8 cross-exam 轮 (其他模式忽略)
user_namestring≤24 字, 在 sub-agent prompt 里出现的「你」称呼
conversation_idstring续聊已有 conversation. 空 = 新建
active_agent_idsarray<string>本次只激活子集 (按 webapp toggle 模拟)
04

SSE 事件流

响应是标准 SSE: 每行 data: <JSON>, 事件之间空行分隔。

type时机字段
conversation首个id (= conversation_id, 用于 webapp 查看历史)
team_status每个 wave 切换stage / round / total_rounds / model
agent_spawnedlead 派遣 sub-agentagent_id / agent_name / code / wave / tool_id
agent_message_deltasub-agent 流式文字 (可选)agent_id / delta / wave
agent_messagesub-agent 完整发言落地agent_id / agent_name / code / content / wave
agent_thinking_deltasub-agent 思考流 (webapp 折叠卡)agent_id / delta
inter_round_directivedebate 轮间 lead MECE 议题分配round / sub_issues / focus_next / converged
lead_summary_deltalead 综合报告流delta
lead_summary_resetlead 重写 (清空累计 buffer)
lead_summarylead 综合报告完整content
done终态cost_units / total_used_this_month / per_agent / output_tokens_total
error异常code / message
05

Curl 示例 (raw SSE)

bash

curl -N -X POST https://www.hipmm8.com/v1/teams/v2/chat \
  -H "Authorization: Bearer hipmm_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agents": [
      {"id":"pm","name":"产品经理","code":"O-A-H-X-ED-AR-VE-LT","role":"用户痛点+商业可行性"},
      {"id":"eng","name":"工程师","code":"I-C-L-B-ID-PR-SE-ST","role":"技术复杂度"}
    ],
    "mode": "debate",
    "rounds": 2,
    "prompt": "PMM8 应该如何打造为爆款",
    "user_name": "Leo"
  }'
06

Python SDK · 6 模式 + 落地 markdown

python

# pip install hipmm
from hipmm import HiPMM

agents = [
  {"id":"pm","name":"产品经理","code":"O-A-H-X-ED-AR-VE-LT","role":"用户痛点+商业可行性"},
  {"id":"eng","name":"工程师","code":"I-C-L-B-ID-PR-SE-ST","role":"技术复杂度+维护成本"},
  {"id":"mkt","name":"市场","code":"O-A-L-X-ED-AR-VE-LT","role":"用户增长+渠道"},
  {"id":"usr","name":"终端用户","code":"I-C-H-X-ID-PR-VE-ST","role":"实际使用感受"},
]

with HiPMM(api_key="hipmm_sk_xxx", base_url="https://www.hipmm8.com") as cli:
    # —— debate (推荐) ——
    r = cli.teams.debate(
        agents=agents,
        prompt="PMM8 试用免费 3 天 vs 永久免费 — 哪个更利于扩张?",
        rounds=2,
        user_name="Leo",
        save_to="result-debate.md",   # ★ 自动落地 markdown
    )
    print(f"conv={r.conversation_id}  cost={r.cost_units}u  summary={len(r.lead_summary)}字")

    # —— 其他 5 模式 ——
    cli.teams.concurrent(agents=agents, prompt="...", save_to="r-concurrent.md")
    cli.teams.sequential(agents=agents, prompt="...", save_to="r-sequential.md")
    cli.teams.red_blue  (agents=agents, prompt="...", save_to="r-redblue.md")
    cli.teams.pipeline  (agents=agents, prompt="...", save_to="r-pipeline.md")
    cli.teams.auto      (agents=agents, prompt="...", save_to="r-auto.md")

    # —— 低级 API: 自渲染实时进度 ——
    for ev in cli.teams.stream(agents=agents, mode="debate", prompt="..."):
        if ev["type"] == "agent_message":
            print(f"[{ev['agent_name']}] {ev['content'][:60]}...")
        elif ev["type"] == "done":
            print(f"DONE cost={ev['cost_units']}u")

    # —— AI 自动派生 agent ——
    out = cli.teams.derive_agents(topic="PMM8 商业化方向", count=0)
    agents2 = out["data"]["agents"]
    cli.teams.debate(agents=agents2, prompt="...")
07

TypeScript SDK · 6 模式 + 实时回调

typescript

// npm install hipmm
import { HiPMM } from "hipmm";
import { teamsResultToMarkdown } from "hipmm/resources/teams";
import { writeFileSync } from "fs";

const cli = new HiPMM({
  apiKey: "hipmm_sk_xxx",
  baseUrl: "https://www.hipmm8.com",
});

const agents = [
  { id: "pm",  name: "产品经理", code: "O-A-H-X-ED-AR-VE-LT", role: "用户痛点+商业可行性" },
  { id: "eng", name: "工程师",   code: "I-C-L-B-ID-PR-SE-ST", role: "技术复杂度+维护成本" },
  { id: "mkt", name: "市场",     code: "O-A-L-X-ED-AR-VE-LT", role: "用户增长+渠道" },
  { id: "usr", name: "终端用户", code: "I-C-H-X-ID-PR-VE-ST", role: "实际使用感受" },
];

// —— debate + 实时回调 ——
const r = await cli.teams.debate({
  agents,
  prompt: "PMM8 试用免费 3 天 vs 永久免费 — 哪个更利于扩张?",
  rounds: 2,
  userName: "Leo",
  onEvent: (ev) => {
    if (ev.type === "agent_message") {
      console.log(`[${ev.agent_name}] ${(ev.content as string).slice(0, 60)}...`);
    }
  },
});
console.log(`conv=${r.conversationId}  cost=${r.costUnits}u`);
writeFileSync("result-debate.md", teamsResultToMarkdown(r));

// —— 其他 5 模式 ——
await cli.teams.concurrent({ agents, prompt: "..." });
await cli.teams.sequential({ agents, prompt: "..." });
await cli.teams.redBlue   ({ agents, prompt: "..." });
await cli.teams.pipeline  ({ agents, prompt: "..." });
await cli.teams.auto      ({ agents, prompt: "..." });

// —— 低级 API + AbortSignal ——
const ctrl = new AbortController();
setTimeout(() => ctrl.abort(), 60_000); // 60s 强制超时
for await (const ev of cli.teams.stream({ agents, mode: "debate", prompt: "...", signal: ctrl.signal })) {
  if (ev.type === "lead_summary_delta") process.stdout.write(ev.delta as string);
  if (ev.type === "done") break;
}
08

自动派生 agent · POST /v1/teams/v2/agents/derive

懒得手填 agent? AI 根据议题自动定 2-6 个最相关 PMM-8+ 人格. 1 unit/调用.

bash

curl -X POST https://www.hipmm8.com/v1/teams/v2/agents/derive \
  -H "Authorization: Bearer hipmm_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"topic":"PMM8 商业化方向","count":0}'

response

{
  "success": true,
  "data": {
    "agents": [
      {"id":"...","name":"...","code":"O-A-H-X-...","role":"..."},
      ...
    ],
    "topic": "PMM8 商业化方向",
    "auto_count": true,
    "decided_count": 4
  }
}
09

会话管理

API 创的 conversation 自动跟 webapp 同源。增删查改:

端点说明
GET /v1/teams/v2/conversations列出全部 (JWT only — webapp 用)
GET /v1/teams/v2/conversations/{cid}拉取完整内容 (JWT)
PATCH /v1/teams/v2/conversations/{cid}重命名 (JWT)
DELETE /v1/teams/v2/conversations/{cid}删除 + 同步清 bridge SDK 状态 (JWT)

webapp 同步可见

API 触发的 conversation 立即出现在 webapp /teams 左侧列表 (按更新时间排序), 点开即可看到完整 SSE 流回放, 包含 agent 卡片 / wave 进度 / 推理过程 / 综合报告 — 跟 webapp 直接触发的体验一模一样.
10

错误码

HTTPcode原因
400TEAM_SIZE_EXCEEDEDagent 数超 plan 上限 (Pro 6 / Max+Ent 10, 超管 override 优先)
400CONVERSATION_LIMIT_EXCEEDEDTeams 会话数超 plan 上限
400NO_ACTIVE_AGENTSactive_agent_ids 都不在 agents 列表里
401AUTH_REQUIRED未传 JWT 或 hipmm_sk_* key
403PLAN_REQUIREDTeams 需 Pro 或以上套餐
403ENDPOINT_NOT_ALLOWEDFree/Starter API key 不允许 Teams 端点
403ACCOUNT_SUSPENDED账号已冻结
500TEAMS_BRIDGE_UNAVAILABLEbridge 不可达 (运维问题, 报支持 + request_id)