文档

PROMIVO 如何运作

部署智能体、构建工作流以及从自有系统调用平台所需的核心概念。

智能体与版本

一个智能体由目录中的一个条目和一个或多个不可变版本组成。版本包含系统提示词、模型配置、可调用的工具、输入与输出模式、执行限制，以及自动风险上限。

发布更新会创建新版本并移动当前指针。已有版本永不被修改，因此正在进行的运行会保持它开始时的行为。

权限与风险

每个工具都声明一个风险等级。智能体版本声明它可在无人参与下执行的最高等级。

READ获取、搜索、汇总。不改变任何内容。
WRITE发送邮件、发布更新、新增或更新记录。
DESTRUCTIVE删除数据或支出资金。

超出上限的工具调用会被拒绝，记录为等待审批的任务，并作为「未执行」回报给模型。运行继续，副作用不会发生。

工作流节点

节点	作用
`TRIGGER`	入口点。手动、Webhook、定时或事件触发。
`AI`	以插值后的输入模板运行一个智能体。
`HTTP`	调用任意公开的 HTTP 端点。指向私有网段的请求会被拦截。
`CONDITION`	依据运行上下文中的某个值进行分支。
`TRANSFORM`	把数据重塑为一个新对象。
`EMAIL`	通过已配置的服务商发送邮件。
`WEBHOOK`	向外发送带签名的 JSON 负载。
`DELAY`	在一次运行内最多等待 300 秒。
`DATABASE`	记录一条备注，或读取近期的执行记录。
`OUTPUT`	定义该工作流的最终结果。

模板

节点配置会插入运行上下文中的值。系统不做表达式求值，因此模板永远无法执行代码。

{{trigger.email}}                  → the trigger payload
{{steps.qualify.output.score}}     → an earlier node result
{{workflow.name}}                  → workflow metadata

公开 API

在API 密钥页面上创建一个限定范围的密钥。密钥只显示一次，系统只保存它的哈希值。

POST /api/agents/run
Authorization: Bearer pmv_live_…
Content-Type: application/json

{ "agentId": "<uuid>", "input": { "topic": "Q4 planning" } }

所有响应都使用同一个信封结构：

{ "ok": true,  "data": { … } }
{ "ok": false, "error": { "code": "…", "message": "…" } }

接口端点

GET /api/agents
POST /api/agents/run
GET /api/workflows
POST /api/workflows
POST /api/workflows/:id/run
GET /api/executions
GET /api/executions/:id
GET /api/usage

Webhook 触发器

Webhook 工作流会获得一个公开令牌和一个仅在创建时显示一次的签名密钥。请用该密钥对原始请求体签名。

POST /api/webhooks/workflow/<token>
x-promivo-secret:    <signing secret>
x-promivo-signature: <hex HMAC-SHA256 of the raw body>
x-idempotency-key:   <optional; makes redelivery safe>

{ "email": "lead@example.com", "message": "…" }