Motivation Money集成
AI 智能体
AI 智能体如何通过 API 操作 Motivation Money。
Motivation Money 支持人类和 AI 智能体共同操作。REST API、CLI、作用域 API 密钥、结构化 JSON 响应和 OpenAPI 规范使 LLM 驱动的智能体能够端到端管理薪资发放——无论通过 HTTP 调用还是 Shell 命令。
为什么适合智能体
- 结构化 I/O。 每个端点接受并返回具有一致 Schema 的 JSON。无需解析 HTML，无歧义格式。
- 作用域权限。 为智能体发放具有精确作用域的 API 密钥。只读智能体获取
payroll:read+employees:read。全自动智能体获取payroll:*+employees:*。 - 显式状态机。 薪资发放批次遵循清晰的生命周期（草稿 > 已确认 > 付款中 > 已完成）。智能体始终知道当前所处状态及可用操作。
- 幂等写入。 每个创建操作需要幂等键。智能体可安全重试而不会创建重复记录。
- OpenAPI 规范。 获取
/api/v1/openapi.json即可为任意 LLM 框架自动生成工具定义。
两种路径：API 或 CLI
智能体可通过 REST API（HTTP 请求）或 CLI（Shell 命令）与 Motivation Money 交互。两者使用相同的 API 密钥认证并返回相同的数据。
| 方式 | 适用场景 |
|---|---|
| REST API（curl/HTTP） | 具有原生 HTTP 工具支持的框架中的智能体（OpenAI functions、Anthropic tool use） |
CLI（mp） | 执行 Shell 命令的智能体（Claude Code、Devin、Cursor、自定义智能体） |
示例：智能体驱动的薪资发放
每个步骤展示 API 和 CLI 两种方式。
1. 创建批次
API：
curl -X POST https://money.motivationlabs.ai/api/v1/runs \
-H "Authorization: Bearer mpk_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"period_start": "2026-03-01T00:00:00Z",
"period_end": "2026-03-31T23:59:59Z",
"pay_date": "2026-04-05T00:00:00Z",
"label": "March 2026 Payroll",
"type": "regular"
}'CLI：
mp runs create --period-start 2026-03-01 --period-end 2026-03-31 \
--pay-date 2026-04-05 --label "March 2026 Payroll" -f json2. 审查草稿
API：
curl https://money.motivationlabs.ai/api/v1/runs/{id}/payouts \
-H "Authorization: Bearer mpk_live_..."CLI：
mp runs payouts <run-id> -f json智能体可以检查每笔付款金额、验证合计并在继续前标记异常。
3. 检查余额
API：
curl -X POST https://money.motivationlabs.ai/api/v1/runs/{id}/balance-check \
-H "Authorization: Bearer mpk_live_..."CLI：
mp runs balance-check <run-id>如果 sufficient 为 false，智能体可通知人工从 Safe 转账。
4. 确认并执行
API：
curl -X POST https://money.motivationlabs.ai/api/v1/runs/{id}/confirm \
-H "Authorization: Bearer mpk_live_..."
curl -X POST https://money.motivationlabs.ai/api/v1/runs/{id}/execute \
-H "Authorization: Bearer mpk_live_..."CLI：
mp runs confirm <run-id>
mp runs execute <run-id> --wait # 阻塞直至所有付款完成--wait 标志对智能体特别有用——它会自动轮询并在所有付款到达终态后返回。
5. 轮询完成状态（仅 API）
curl -X POST https://money.motivationlabs.ai/api/v1/runs/{id}/sync \
-H "Authorization: Bearer mpk_live_..."如果使用 CLI 的 --wait，此步骤自动处理。否则，智能体轮询 /sync 直至所有付款到达终态。
6. 报告结果
API：
curl https://money.motivationlabs.ai/api/v1/runs/{id} \
-H "Authorization: Bearer mpk_live_..."CLI：
mp runs get <run-id> -f json智能体读取最终批次状态并生成摘要：已支付多少员工、总金额、是否有失败。
生成工具定义
对于使用工具/函数调用的框架（OpenAI、Anthropic、LangChain 等），可从 OpenAPI 规范生成工具 Schema：
curl https://money.motivationlabs.ai/api/v1/openapi.json将每个端点转换为工具定义。例如，"创建批次"端点变为：
{
"name": "create_payroll_run",
"description": "Create a new payroll run for the given period",
"parameters": {
"type": "object",
"properties": {
"period_start": { "type": "string", "format": "date-time" },
"period_end": { "type": "string", "format": "date-time" },
"pay_date": { "type": "string", "format": "date-time" },
"label": { "type": "string" },
"type": { "type": "string", "enum": ["regular", "ad_hoc", "reimbursement"] }
},
"required": ["period_start", "period_end"]
}
}推荐的智能体作用域
| 智能体角色 | 作用域 |
|---|---|
| 只读监控 | payroll:read、employees:read、treasury:read、audit:read |
| 薪资发放运营 | payroll:read、payroll:write、payroll:execute、employees:read、treasury:read |
| 全自动化 | payroll:*、employees:*、treasury:read、audit:read、webhooks:manage |
用于异步智能体的 Webhooks
智能体可注册 Webhook 接收推送通知，而非轮询：
curl -X POST https://money.motivationlabs.ai/api/v1/webhooks \
-H "Authorization: Bearer mpk_live_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-agent.example.com/webhook",
"events": ["run.completed", "run.failed", "payout.failed"]
}'智能体的 Webhook 处理器接收结构化 JSON 负载并可立即响应——重试失败付款、通知相关方或更新内部账本。
安全注意事项
- 执行操作需人工审批。 授予智能体
payroll:write以创建和准备批次，但由人工确认和执行。确保资金转移有人工参与。 - 使用短期 API 密钥。 为智能体密钥设置过期时间并定期轮换。
- 监控审计日志。 每个 API 操作都记录了 API 密钥 ID。使用审计日志审查智能体活动。
- 从测试批次开始。 使用测试批次功能以小额金额验证智能体的工作流，然后再上线。