跳到主要内容

智能体 Webhook

智能体 Webhook 允许外部系统启动已配置的智能体。创建一个由 Webhook 触发的智能体，向其发送请求，Almirant 会为该请求创建唯一的规范作业。

快速开始​

  1. 打开 Agents，然后选择 Create agent。
  2. 完成 Base、Prompt，并在适用时完成 MCP 步骤。
  3. 在 Trigger 中选择 Webhook 并保存智能体。Almirant 会显示一个生产 URL 和一个测试 URL。
  4. 在调用系统中将生产 URL 保存为密钥，并发送带有 Idempotency-Key 的 POST 请求。

生产 URL 的形式如下：

https://<your-almirant-host>/webhooks/agents/<agent-id>?token=<webhook-token>

令牌是凭据的一部分。请勿将其包含在版本控制、日志或公开工单中。

发送 POST 请求​

POST 会使用已保存的系统提示词启动一个智能体作业，并附加调用方可选的提示词和元数据。

curl --request POST \
  --url 'https://almirant.example.com/webhooks/agents/agent_123?token=replace-with-secret-token' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-9182-import-v1' \
  --data '{
    "prompt": "Importa el pedido e informa de cualquier error de validación.",
    "metadata": {
      "orderId": "9182",
      "source": "warehouse"
    }
  }'

首次成功投递会返回已创建的作业：

{
  "success": true,
  "data": {
    "jobId": "job_123",
    "status": "queued",
    "created": true,
    "replayed": false
  }
}

如果网络故障导致无法确定 Almirant 是否收到请求，请使用相同的 Idempotency-Key 再次发送。重放会返回相同的规范作业，而不是启动另一个作业：

{
  "success": true,
  "data": {
    "jobId": "job_123",
    "status": "queued",
    "created": false,
    "replayed": true
  }
}

请求契约​

部分要求
URL必须提供 agent-id 和 token 查询参数。凭据无效或缺失时返回 401。
Idempotency-Key在 POST 中可选；每个逻辑事件使用一个不透明且稳定的值。必须为 1 到 255 个 UTF-8 字节，不得为空或包含控制字符。无效值会返回带有 invalid_idempotency_key 的 400。
prompt可选字符串，在本次运行中作为调用方输入附加。
metadata可选对象。保存的智能体提示词可插入元数据值，例如 {{metadata.orderId}}。
outputBinding可选的字符串到字符串映射，用于智能体中已配置的输出目标。不能选择新的投递 URL。

请求体仅接受 prompt、metadata 和 outputBinding。调用方控制的 deliveryUrl 会被拒绝。

测试、GET 和 POST 行为​

测试端点会检查 URL 是否可访问，不会将任何作业加入队列：

POST https://<your-almirant-host>/webhook-test/agents/<agent-id>?token=<webhook-token>

生产 GET 端点会使用已保存的系统提示词启动作业。GET 不接受调用方输入，也不提供 POST 的幂等响应语义。在可能重试的集成中请使用 POST。

由 Webhook 触发的智能体使用手动调度，因为它们由传入请求而非调度器启动。Webhook 智能体必须保持启用状态并配置为该触发器；否则端点返回 409。

故障排除​

响应含义操作
400 invalid_idempotency_keyPOST 密钥为空、过长或包含控制字符。生成简短且稳定的事件标识符。
400 invalid_output_binding提供的绑定与智能体的输出配置不匹配。检查已配置的输出目标和绑定字段名称。
401 invalid_webhook_credentialsURL 令牌缺失、不正确或已失效。复制智能体当前的 URL，并替换已保存的密钥。
409智能体无法作为 Webhook 智能体运行。重新启用它，并确认其触发器为 Webhook。

相关页面​