# エージェント

> Piqline のエージェントに回答させます。ターン、ステータス、会話。

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

エージェントは、HTTP で呼び出すダッシュボードのアシスタントです。リクエストを読み、ツールを選んで実行し、出典付きで回答します。チャットと同じエンジンを使い、キー自身が呼び出せるツールだけを使います。

## エージェント一覧

| エージェント | 役割 |
| --- | --- |
| `piqline` | ワークスペースのパイプライン。コーパス、モニタリング、ボード、テーブル、ブックマーク。 |
| `requete` | 的確な 1 つの質問に対して、Web、レジストリ、アーカイブから日付付きの事実を返します。 |
| `facebook` | Marketplace と公開グループをライブで読み取ります。 |
| `linkedin` | 公開投稿をもとにした、採用、モニタリング、案件の発見。 |
| `upwork` | Upwork の案件を読み取り、スコアを付け、ナレッジベースをもとに回答を作成します。 |
| `onboarding` | ワークスペースの初期設定をガイドします。ニーズ、ソース、ホームボード、アラート。オーナーと管理者のみ。 |

キーには `agents` スコープが必要です。`GET https://piqline.com/api/v1/agents` は、エージェントの一覧と、エージェントごとにキーで呼び出せるツールを返します。

## 1 ターンを実行する

```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` に内容があります。`messages` を送り返しつつ、`input` にテキストで回答してください。
- **`requires_approval`。** エージェントは、ソースの購読などのアクションを提案しましたが、実行していません。実行するには、`act` スコープを持つキーで、`pending[].tool` に示されたツールを `pending[].input` を使って `POST https://piqline.com/api/v1/tools/{nom}` から自分で呼び出します。

## ストリーミング

`"stream": true` を指定すると、レスポンスは Server-Sent Events のストリームとして届きます。ダッシュボードのチャットと同じストリームです。`curl` では、`-N` を付けると届く様子を確認できます。

## クレジットと所要時間

1 ターンでワークスペースのクレジットを消費し、月間上限から差し引かれます。1 ターンの所要時間は、数秒から数十秒です。クライアント側で 5 分のタイムアウトを設定してください。

既定では、キーごとに 1 分あたり 10 ターンまで実行できます。[制限](/ja/docs/api/authentication#制限)を参照してください。
