# 智能体

> 让 Piqline 智能体作答：一轮对话、一个状态、一段会话。

Source: https://piqline.com/zh/docs/api/agents

智能体就是通过 HTTP 调用的控制台助手：它读取你的请求，选择工具，运行工具，并连同来源一起作答。它使用与聊天相同的引擎，并且只能使用你的密钥自己可以调用的工具。

## 智能体列表

| 智能体 | 作用 |
| --- | --- |
| `piqline` | 工作区管道：语料库、监控、看板、表格和书签。 |
| `requete` | 一个精确的问题，答案是取自网络、注册库和档案的带日期的事实。 |
| `facebook` | 实时读取 Marketplace 和公开群组。 |
| `linkedin` | 依据公开帖子做招聘、监控和机会发现。 |
| `upwork` | 读取 Upwork 职位，依据你的知识库评分并答复。 |
| `onboarding` | 引导式工作区设置：需求、来源、首页看板、提醒。仅限所有者和管理员。 |

密钥需要 `agents` scope。`GET https://piqline.com/api/v1/agents` 列出所有智能体，以及每个智能体中你的密钥可以调用的工具。

## 运行一轮对话

```http
POST https://piqline.com/api/v1/agents/{agent}
Content-Type: application/json
```

| 字段 | 类型 | 作用 |
| --- | --- | --- |
| `input` | 文本，最多 20,000 个字符 | 你的消息。 |
| `messages` | 数组 | 之前的对话，格式与上一次调用返回的相同。 |
| `model` | 文本 | 助手提供的模型 ID。未知的 ID 会被替换为默认模型。 |
| `reasoning` | `low`、`medium` 或 `high` | 推理强度，仅适用于支持该参数的模型。 |
| `stream` | 布尔值 | `true`：流式响应（见下文）。 |

至少发送 `input` 或 `messages` 之一。

```bash tab="curl"
curl -s https://piqline.com/api/v1/agents/piqline \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Quelles sources sont en erreur, et depuis quand ?"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/agents/piqline", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ input: "Quelles sources sont en erreur, et depuis quand ?" }),
});
const data = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/agents/piqline",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={"input": "Quelles sources sont en erreur, et depuis quand ?"},
)
data = response.json()
```

响应：

| 字段 | 含义 |
| --- | --- |
| `agent` | 你所请求的智能体 |
| `status` | `completed`、`requires_input` 或 `requires_approval`（见下文） |
| `text` | 智能体的回答 |
| `tool_calls` | 本轮调用的工具：`tool`、`state`、`input`，以及 `output` 或 `error` |
| `pending` | 等待你答复的内容：`kind`（`input` 或 `approval`）、`tool`、`input`，若为审批，还有 `approval_id` |
| `messages` | 完整的对话，下次调用时原样发回 |

## 继续对话

把上一次响应中的 `messages` 数组发回，并把你的新消息放在 `input` 中：

```bash
# Premier tour : on garde la réponse.
curl -s https://piqline.com/api/v1/agents/piqline \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Quelles sources sont en erreur ?"}' > tour1.json

# Deuxième tour : on renvoie la conversation.
jq '{messages: .messages, input: "Et depuis quand ?"}' tour1.json \
  | curl -s https://piqline.com/api/v1/agents/piqline \
      -H "Authorization: Bearer $PIQLINE_API_KEY" \
      -H "Content-Type: application/json" \
      -d @-
```

## 智能体何时停下

- **`completed`。** 智能体已作答，`text` 中是它的回答。
- **`requires_input`。** 智能体提出一个问题或给出一张卡片，例如在多个来源之间做选择。`pending` 对此作了说明。请在 `input` 中用文字回答，并把 `messages` 发回。
- **`requires_approval`。** 智能体提出一项操作（例如订阅某个来源），但不会执行。要执行它，请使用带有 `act` scope 的密钥，通过 `POST https://piqline.com/api/v1/tools/{nom}` 自行调用 `pending[].tool` 中指明的工具，并传入 `pending[].input`。

## 流式响应

设置 `"stream": true` 后，响应以 Server-Sent Events 流的形式到达：与控制台聊天使用相同的流。使用 `curl` 时，加上 `-N` 可以实时查看。

## 积分与耗时

每一轮都会消耗工作区积分，从每月上限中扣除。一轮对话需要几秒到几十秒。请在客户端设置 5 分钟的超时。

默认情况下，每个密钥每分钟可运行 10 轮：参见[限制](/zh/docs/api/authentication#限制)。
