API 入门 | Hast Docs

从你的服务端调用 AIP 中已保存的 Agent，并读取对话结果。API 密钥在 AIP 工作台管理；REST API 和 MCP 使用相同的密钥与权限。完整接口见 API 参考。

准备地址与密钥

在 AIP 切换到目标 Profile（业务身份）。先创建并调试 Agent，确认已保存配置并启用。
打开管理 API 密钥，创建密钥，访问范围选择“单 Agent 对话”，再选择要调用的 Agent。
勾选“发送消息”（agent:invoke）。它同时包含“读取对话”（agent:conversations:read），可读取该 Agent 的全部历史对话，包括其他集成创建的对话。
创建后立即复制完整密钥；页面之后不会再次显示完整值。

在服务端终端设置环境变量。生产环境地址如下，开发或自部署环境请使用对应的后端地址：

export HAST_API_BASE='https://backend.hast.so/api/public/v1'
export HAST_API_KEY='<你的单 Agent 对话密钥>'

发送第一条任务

curl --fail-with-body --request POST \
  --url "$HAST_API_BASE/agent/prompts" \
  --header "Authorization: Bearer $HAST_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"request_id":"message-001","prompt":"请说明你的职责，以及可以帮助我完成哪些工作。"}'

请求使用密钥绑定的 Agent 及其已保存配置。省略 session_id 会创建对话；继续对话时，加入响应返回的 session_id。每条新消息使用新的 request_id，重试同一条消息时保持请求内容和标识一致。

HTTP 202 表示请求已接收。保存响应中的 session_id 和 request_id，接下来读取事件，确认本轮运行结果。

读取执行过程

export SESSION_ID='<响应中的 session_id>'
curl --fail-with-body \
  "$HAST_API_BASE/agent/sessions/$SESSION_ID/events?after=0&limit=100" \
  --header "Authorization: Bearer $HAST_API_KEY"

响应包含 events、next_after 和 has_more。后续将 next_after 作为 after 继续读取；has_more 为 true 时继续翻页，即使本页没有可见事件。暂时没有新事件时，间隔一段时间再查询。

此接口返回用户消息、Agent 回复和运行状态。找到 run_id 与本轮回执 request_id 一致的 run.completed、run.failed 或 run.interrupted，才能判断本轮结束。message.completed 只表示一条消息完成。详细处理方式见会话事件与 SSE。

单 Agent 对话使用 JSON 轮询，不提供 SSE 路径。可以通过 GET /agent/sessions 查找该 Agent 的历史对话，再读取对应事件。

使用 Profile API key

需要按功能访问当前业务身份的资源时，在管理 API 密钥创建“Profile API key”，按需授权：

用途	权限与入口
查看已保存的 Agent 配置	`webhooks:read`，`GET /webhooks`
调用指定 Agent	`webhooks:write`，`POST /webhooks/{hook_id}/invoke`
管理知识库、渠道、CRM 或定时任务	对应资源的读写权限，见 API 参考
提交普通任务并读取事件	`prompts:write` 和 `sessions:read`，`POST /prompts` 与 `/sessions/{id}/events`

写入权限包含对应读取权限。Profile key 的 /prompts 创建普通任务会话，不会自动应用某个已保存的 AIP Agent 配置；调用已配置的 Agent 时使用上表中的 /webhooks/{hook_id}/invoke，或使用本页的单 Agent 对话流程。

普通任务可通过 /sessions/{id}/events/stream 接收 SSE，见 SSE 接入。Profile key 与单 Agent 对话 key 的接口范围不同，不能混用 /agent/* 和普通任务路径。

继续接入

在 API 参考查看参数、响应和 OpenAPI JSON。使用外部 Agent 客户端时阅读 MCP 接入；通过 Agent 详情页的完整 Hook URL 调用时阅读 Webhook HTTP 接入。