# 에이전트

> Piqline 에이전트에게 답하게 하기: 턴, 상태, 대화.

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

에이전트는 HTTP로 호출하는 대시보드 어시스턴트입니다. 요청을 읽고, 도구를 고르고, 실행한 뒤 출처와 함께 답합니다. 채팅과 같은 엔진을 사용하며, 키가 직접 호출할 수 있는 도구만 가집니다.

## 에이전트 목록

| 에이전트 | 역할 |
| --- | --- |
| `piqline` | 워크스페이스 파이프라인: 코퍼스, 모니터링, 보드, 테이블, 북마크. |
| `requete` | 정확한 질문 하나에 대해 웹, 등록부, 아카이브에서 가져온 날짜가 있는 사실. |
| `facebook` | Marketplace와 공개 그룹을 실시간으로. |
| `linkedin` | 공개 게시물에서 채용, 모니터링, 기회. |
| `upwork` | Upwork 일감을 읽고, 점수를 매기고, 지식 베이스를 바탕으로 답안 작성. |
| `onboarding` | 워크스페이스 설정 안내: 니즈, 소스, 홈 보드, 알림. 소유자와 관리자 전용. |

키에는 `agents` 스코프가 필요합니다. `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`에 내용이 설명되어 있습니다. `messages`를 다시 보내면서 `input`에 텍스트로 답하십시오.
- **`requires_approval`.** 에이전트가 소스 구독 같은 작업을 제안하지만 실행하지는 않습니다. 실행하려면 `pending[].tool`에 지정된 도구를 `pending[].input`으로 직접 호출하십시오. `POST https://piqline.com/api/v1/tools/{nom}`을 사용하며, 키에 `act` 스코프가 있어야 합니다.

## 스트리밍

`"stream": true`를 지정하면 응답이 Server-Sent Events 스트림으로 도착합니다. 대시보드 채팅과 같은 스트림입니다. `curl`에서는 `-N`을 추가하면 도착하는 대로 볼 수 있습니다.

## 크레딧과 소요 시간

한 턴은 워크스페이스 크레딧을 사용하며, 월간 한도에서 차감됩니다. 한 턴은 몇 초에서 수십 초가 걸립니다. 클라이언트에는 5분 타임아웃을 설정하십시오.

키 하나로 기본적으로 분당 10턴을 실행할 수 있습니다. [한도](/ko/docs/api/authentication#한도)를 참조하십시오.
