# 도구

> 에이전트의 도구를 하나씩 호출합니다. 스코프와 입력을 함께 안내합니다.

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

Piqline 에이전트는 도구로 일합니다. 코퍼스 읽기, 실시간 검색, 쓰기, 실행이 있습니다. API는 모든 도구를 같은 형태로 제공합니다. 호출할 수 있는 도구는 92개이며, [카탈로그](#카탈로그)에 스코프와 함께 나열되어 있고, [레퍼런스](/ko/docs/api/reference)에는 각 도구의 매개변수와 호출 예제가 있습니다.

## 도구 목록 조회

```http
GET https://piqline.com/api/v1/tools
GET https://piqline.com/api/v1/tools?agent=linkedin
GET https://piqline.com/api/v1/tools/{nom}
```

`agent`에는 `all`(기본값), `piqline`, `requete`, `facebook`, `linkedin`, `upwork`, `onboarding`을 사용할 수 있습니다. 목록의 각 도구에는 다음 필드가 있습니다.

| 필드 | 의미 |
| --- | --- |
| `name` | 호출할 때 사용하는 도구 이름 |
| `description` | 에이전트가 읽는 영어 도구 설명 |
| `agents` | 이 도구를 가진 에이전트 |
| `requires` | 필요한 스코프 |
| `callable` | 키로 호출할 수 있으면 `true` |
| `missing_scopes` | 키에 없는 스코프 |
| `confirmation_in_chat` | 도구 실행 전에 채팅이 확인을 요청하면 `true` |
| `read_only` | 도구가 아무것도 변경하지 않으면 `true` |
| `input_schema` | 입력의 JSON Schema |

키로 호출할 수 없는 도구도 목록에 남으며, `callable: false`와 `missing_scopes`가 함께 표시됩니다. `GET /api/v1/tools/{nom}`은 도구 하나에 대해 같은 항목을 반환하며, `confirmation_in_chat`과 `read_only`는 포함하지 않습니다.

## 도구 호출하기

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

JSON 본문이 도구의 입력이며, `input_schema`가 그 형태를 설명합니다. 입력이 없는 도구는 빈 본문을 받습니다.

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/searchItems \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"levée de fonds","limit":5}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/searchItems", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "levée de fonds", limit: 5 }),
});
const data = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/searchItems",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={"query": "levée de fonds", "limit": 5},
)
data = response.json()
```

응답에는 도구 이름과 출력이 들어 있으며, 에이전트가 읽는 출력과 같습니다.

```json
{
  "tool": "searchItems",
  "output": {
    "count": 1,
    "hasMore": true,
    "items": [
      {
        "id": "5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70",
        "sourceId": "e1f4b2a8-6c3d-4957-b0a1-82d5c7f3e964",
        "title": "Titre de l’article",
        "excerpt": "Début du texte…",
        "itemType": "article",
        "platform": "rss",
        "sourceName": "Blog du secteur",
        "sourceBadge": null,
        "occurredAt": "2026-10-27T08:14:00.000+00:00",
        "url": "https://exemple.fr/article",
        "language": "fr"
      }
    ]
  }
}
```

`occurredAt`은 항목에 표시되는 날짜입니다. `getItem`은 `detectedAt`(Piqline이 처음 본 시점), `lastSeenAt`(마지막으로 본 시점), `publishedAt`도 반환합니다.

오류는 `application/problem+json`으로 반환됩니다. [오류](/ko/docs/api/errors)를 참조하십시오.

## 누가 무엇을 호출할 수 있는가

- **키는 만든 사람의 역할로 제한됩니다.** 그 역할이 열어 주지 않는 도구는 `403 forbidden`으로 응답합니다. 쓰기 도구, 실행 도구, `onboarding` 에이전트는 소유자와 관리자 전용입니다.
- **채팅 카드는 API에 없습니다.** `askUser`, `proposeSources`, `proposeBoard` 등은 사람에게 표시되는 카드이며 아무것도 실행하지 않습니다. 이 도구들은 `404 not_found`로 응답합니다. 이런 대화를 하려면 [에이전트](/ko/docs/api/agents)를 실행하십시오.
- **실행 도구는 확인을 기다리지 않습니다.** 채팅에서는 확인을 요청하지만, `act` 스코프로 직접 호출하면 즉시 실행됩니다.
- **실시간 읽기는 크레딧을 사용합니다.** `explore` 스코프의 도구는 워크스페이스의 월간 한도에서 크레딧을 차감합니다.

## 카탈로그

### 코퍼스와 워크스페이스 읽기

Piqline 에이전트의 도구입니다. 워크스페이스가 이미 수집한 내용을 읽습니다. 크레딧을 사용하지 않으며 아무것도 쓰지 않습니다.

| 도구 | 유형 | 스코프 | 역할 |
| --- | --- | --- | --- |
| [`getCoverageStats`](/ko/docs/api/reference/corpus#getcoveragestats) | 읽기 | `read` | 수집량과 상태: 합계, 플랫폼별 및 종류별 분포, 분석 기간(`1h`, `24h`, `7d`, `30d`) 동안의 수집 시계열. |
| [`listSources`](/ko/docs/api/reference/corpus#listsources) | 읽기 | `read` | 워크스페이스가 팔로우하는 소스와 항목 수, 상태, 마지막 읽기. |
| [`searchItems`](/ko/docs/api/reference/corpus#searchitems) | 읽기 | `read` | 필터(텍스트, 플랫폼, 종류, 소스)로 항목(게시물, 동영상, 기사, 광고, 일감)을 검색합니다. 필터가 없으면 최신 항목을 반환합니다(최대 40개). |
| [`getItem`](/ko/docs/api/reference/corpus#getitem) | 읽기 | `read` | 항목의 상세: 텍스트, 전사, OCR, 감지된 주제, 의미가 가까운 항목, 관찰 날짜. |
| [`searchPassages`](/ko/docs/api/reference/corpus#searchpassages) | 읽기 | `read` | 긴 문서(Motor가 읽은 PDF)에서 의미로 검색합니다. 질문과 가장 가까운 구절을 항목, 페이지, 섹션 제목과 함께 반환합니다. |
| [`citeItem`](/ko/docs/api/reference/corpus#citeitem) | 읽기 | `read` | 구절이 항목에 글자 그대로 나오는지 확인하고 인용 번호를 반환합니다. 없으면 가장 가까운 구절을 반환합니다. 채팅의 인용 모드의 기반입니다. |
| [`drawDiagram`](/ko/docs/api/reference/corpus#drawdiagram) | 읽기 | `read` | 답변을 SVG 다이어그램(타임라인, 매트릭스, 흐름, 트리 등)으로 그립니다. 색상은 테마 역할에 따르며, SVG는 표시 전에 정제됩니다. 채팅의 다이어그램 모드의 기반입니다. |
| [`createCanvas`](/ko/docs/api/reference/corpus#createcanvas) | 읽기 | `read` | 캔버스(piqline/canvas SDK만 import하는 TSX 파일)를 컴파일하여 바로 표시할 수 있는 코드, 또는 수정해야 할 오류를 반환합니다. 채팅의 캔버스 및 리포트 모드의 기반입니다. |
| [`getTopics`](/ko/docs/api/reference/corpus#gettopics) | 읽기 | `read` | 감지된 주제와 점유율, 그리고 스토리(여러 소스에서 본 같은 주제). |
| [`getSignals`](/ko/docs/api/reference/corpus#getsignals) | 읽기 | `read` | 워크스페이스의 지속성 규칙으로 발생한 열린 신호와 그 선행 시간 및 상태. |
| [`listWorkspaceTables`](/ko/docs/api/reference/corpus#listworkspacetables) | 읽기 | `read` | 워크스페이스에 이미 만들어진 테이블: 이름, 설명, 열과 행의 수, 테이블이 자동으로 채워지는지 여부. |
| [`getWorkspaceTable`](/ko/docs/api/reference/corpus#getworkspacetable) | 읽기 | `read` | JSON으로 된 워크스페이스 테이블: 스키마, 열, 행. 사이트, 앱 또는 에이전트의 기반이나 데이터 공급원으로 쓰입니다(read 스코프). |
| [`listBookmarks`](/ko/docs/api/reference/corpus#listbookmarks) | 읽기 | `read` | 워크스페이스 보관함의 북마크와 폴더: 제목, 유형, 폴더, 상태, 승인 여부. 단어, 상태, 유형으로 선택 필터링할 수 있습니다. |
| [`listEntities`](/ko/docs/api/reference/corpus#listentities) | 읽기 | `read` | 팔로우 중인 엔티티(회사, 브랜드, 공개 계정)와 해당 기간에 연결된 항목. |
| [`listWatchContracts`](/ko/docs/api/reference/corpus#listwatchcontracts) | 읽기 | `read` | 소스에 설정된 모니터링 계약: 의도, 유지할 용어와 제외할 용어, 이벤트. |
| [`checkInvestigation`](/ko/docs/api/reference/corpus#checkinvestigation) | 읽기 | `read` | 가장 최근 Edge 조사 또는 지정한 조사의 상태: 대기 중, 실행 중, 후보와 함께 완료, 또는 실패. |
| [`checkHunt`](/ko/docs/api/reference/corpus#checkhunt) | 읽기 | `read` | 가장 최근 헌트 또는 지정한 헌트의 상태: 단계, 찾은 사람(코드의 판정과 사용자의 판정), 각 조건의 상태와 날짜가 있는 공개 근거(URL, 날짜, 발췌). 연락처는 절대 포함하지 않습니다. |
| [`planSourcePack`](/ko/docs/api/reference/corpus#plansourcepack) | 읽기 | `read` | 목표에 맞는 일관된 소스 묶음을 제안합니다. 아무것도 만들지 않습니다. |
| [`listWidgets`](/ko/docs/api/reference/corpus#listwidgets) | 읽기 | `read` | 이 워크스페이스의 보드에 놓을 수 있는 위젯을 사용자에게 맞게 순위를 매겨 이유와 함께 나열합니다. |
| [`getAdvertiserCampaigns`](/ko/docs/api/reference/corpus#getadvertisercampaigns) | 읽기 | `read` | 워크스페이스 수집 데이터에 있는 광고주의 광고 파일: 광고, 게재 중인 광고, 날짜, 라이브러리, 국가, 읽은 니즈, 월별 신규 광고와 증가 추세, 최신 광고, 신호. 개인은 다루지 않습니다. 크레딧을 사용하지 않습니다. |
| [`listAdSignals`](/ko/docs/api/reference/corpus#listadsignals) | 읽기 | `read` | 매시간 계산되는 워크스페이스의 광고 신호: 캠페인 시작 또는 중단, 증가, 새 국가, 새 플랫폼, 유료 채용, 프로모션, 출시, 새 광고주. 크레딧을 사용하지 않습니다. |
| [`listCollectedAds`](/ko/docs/api/reference/corpus#listcollectedads) | 읽기 | `read` | 이미 읽은 워크스페이스의 광고 수집(Meta, TikTok, Google, LinkedIn): 목록, 또는 수집 이름을 지정하면 분류(각도, 오퍼, 톤, 형식), 속도, 가장 오래 게재된 광고, 라이브러리, 상태, 각도 또는 단어로 필터링한 광고. 크레딧을 사용하지 않습니다. |

### 웹과 공공 등록부 실시간 탐색

웹과 공개 네트워크를 실시간으로 읽습니다. 크레딧을 사용하며, 워크스페이스에는 아무것도 저장되지 않습니다.

| 도구 | 유형 | 스코프 | 역할 |
| --- | --- | --- | --- |
| [`readPage`](/ko/docs/api/reference/direct#readpage) | 실시간 읽기 | `explore` | 공개 웹 페이지를 읽습니다: 제목, 본문(6,000자), 발견된 피드, 링크 30개. |
| [`searchWeb`](/ko/docs/api/reference/direct#searchweb) | 실시간 읽기 | `explore` | 공개 웹을 검색하여 후보 URL을 찾습니다. |
| [`browserRead`](/ko/docs/api/reference/direct#browserread) | 실시간 읽기 | `explore` | 강제 브라우저로 동적 페이지나 보호된 페이지를 읽습니다. `readPage`와 같은 형태입니다. |
| [`waybackHistory`](/ko/docs/api/reference/direct#waybackhistory) | 실시간 읽기 | `explore` | URL의 Wayback Machine 캡처: 첫 캡처와 최근 캡처. |
| [`registryLookup`](/ko/docs/api/reference/direct#registrylookup) | 실시간 읽기 | `explore` | 공개 등록부에서 회사를 조회합니다: Sirene(프랑스), EDGAR(미국), Companies House(영국), OpenCorporates. |
| [`socialCatalog`](/ko/docs/api/reference/direct#socialcatalog) | 실시간 읽기 | `explore` | 소셜 네트워크 읽기 엔드포인트(최대 40개)를 나열하며, 플랫폼별로 필터링할 수 있습니다. |
| [`socialCall`](/ko/docs/api/reference/direct#socialcall) | 실시간 읽기 | `explore` | 소셜 네트워크 읽기 엔드포인트를 호출하여 간략한 항목을 최대 20개 반환합니다. |
| [`previewSource`](/ko/docs/api/reference/direct#previewsource) | 실시간 읽기 | `explore` | 구독하기 전에 소스의 실시간 샘플(5~10개 항목)을 가져옵니다. |
| [`whoSaidItFirst`](/ko/docs/api/reference/direct#whosaiditfirst) | 실시간 읽기 | `explore` | 웹에서 어떤 정보를 누가 가장 먼저 게시했는지를 페이지 단위로, 그리고 사용자의 소스가 그것을 언제 보았는지 알려 줍니다. 주제 또는 항목에서 시작하며, 비공개 워크스페이스 타임라인으로 보관됩니다. |

### Facebook

Facebook 에이전트의 도구입니다. Marketplace 매물과 공개 그룹을 실시간으로 읽습니다.

| 도구 | 유형 | 스코프 | 역할 |
| --- | --- | --- | --- |
| [`findMarketplaceLocation`](/ko/docs/api/reference/facebook#findmarketplacelocation) | 실시간 읽기 | `explore` | 도시 또는 지역 이름을 Marketplace 좌표로 변환합니다. |
| [`searchMarketplace`](/ko/docs/api/reference/facebook#searchmarketplace) | 실시간 읽기 | `explore` | 장소(도시 또는 좌표) 주변의 공개 Marketplace 매물을 키워드로 검색합니다. 최대 3페이지. |
| [`getMarketplaceListing`](/ko/docs/api/reference/facebook#getmarketplacelisting) | 실시간 읽기 | `explore` | 매물의 상세: 설명, 속성, 사진, 배송, Facebook이 제공하는 경우 정확한 날짜. |
| [`getMarketplaceListings`](/ko/docs/api/reference/facebook#getmarketplacelistings) | 실시간 읽기 | `explore` | 매물 2~6개의 상세를 비교 표로 한 번에 가져옵니다. |
| [`getFacebookGroup`](/ko/docs/api/reference/facebook#getfacebookgroup) | 실시간 읽기 | `explore` | 그룹의 공개 프로필: 공개 범위, 규모, 활동, 카테고리, 규칙. |
| [`getFacebookGroupPosts`](/ko/docs/api/reference/facebook#getfacebookgroupposts) | 실시간 읽기 | `explore` | 공개 그룹의 게시물을 3개씩 페이지로 가져옵니다(최대 6페이지). |
| [`getFacebookPost`](/ko/docs/api/reference/facebook#getfacebookpost) | 실시간 읽기 | `explore` | 공개 게시물 또는 릴스의 상세: 텍스트, 작성자, 날짜, 반응, 조회수. |
| [`getFacebookPostComments`](/ko/docs/api/reference/facebook#getfacebookpostcomments) | 실시간 읽기 | `explore` | 공개 게시물의 댓글을 키워드로 필터링할 수 있습니다(최대 3페이지). |

### LinkedIn

LinkedIn 에이전트의 도구입니다. 공개 게시물, 회사 페이지, 광고를 실시간으로 읽습니다. 연락처는 읽지 않습니다.

| 도구 | 유형 | 스코프 | 역할 |
| --- | --- | --- | --- |
| [`searchLinkedinPosts`](/ko/docs/api/reference/linkedin#searchlinkedinposts) | 실시간 읽기 | `explore` | 키워드로 공개 게시물을 실시간으로 최신순 검색합니다(부분 읽기는 결과에 표시됨). 채용 게시물에는 작성자의 직함과 역할을 함께 반환하며, 코드가 계산한 신호(채용, 투자 유치, 출시, 확장, 조직 개편, 가용, 퇴사)를 포함합니다. |
| [`probeLinkedinWatch`](/ko/docs/api/reference/linkedin#probelinkedinwatch) | 실시간 읽기 | `explore` | LinkedIn 모니터링을 구독하기 전에 쿼리 변형 1~3개를 시험하고, 구독에 첨부할 조사 티켓을 반환합니다. |
| [`getLinkedinPost`](/ko/docs/api/reference/linkedin#getlinkedinpost) | 실시간 읽기 | `explore` | 공개 게시물 또는 기사를 읽습니다: 텍스트, 작성자, 날짜, 반응, 신호가 포함된 댓글. |
| [`getLinkedinPostTranscript`](/ko/docs/api/reference/linkedin#getlinkedinposttranscript) | 실시간 읽기 | `explore` | 공개 게시물 동영상의 전사. 전사가 있는 경우에만 과금됩니다. |
| [`getLinkedinCompany`](/ko/docs/api/reference/linkedin#getlinkedincompany) | 실시간 읽기 | `explore` | 공개 회사 페이지: 설명, 직원 수, 업종, 투자 정보, 신호가 포함된 최신 게시물. |
| [`getLinkedinCompanyPosts`](/ko/docs/api/reference/linkedin#getlinkedincompanyposts) | 실시간 읽기 | `explore` | 회사 페이지의 이전 게시물과 신호 요약(채용, 투자, 출시). |
| [`searchLinkedinAds`](/ko/docs/api/reference/linkedin#searchlinkedinads) | 실시간 읽기 | `explore` | 광고 라이브러리를 검색합니다: 광고주, 형식, 날짜, 노출 수. |
| [`getLinkedinAd`](/ko/docs/api/reference/linkedin#getlinkedinad) | 실시간 읽기 | `explore` | 라이브러리 광고의 상세: 타겟팅, 국가별 노출 수, 게재 기간. |
| [`matchLinkedinPosts`](/ko/docs/api/reference/linkedin#matchlinkedinposts) | 실시간 읽기 | `explore` | 공개 게시물을 바탕으로 가용한 사람과 기회를 매칭합니다(검색 두 번). |
| [`getLinkedinProfile`](/ko/docs/api/reference/linkedin#getlinkedinprofile) | 실시간 읽기 | `explore` | 공개 `/in/` 프로필을 제한적으로 읽습니다. 그 사람을 언급하는 공개 게시물에서만 가능합니다. 이 옵션을 켠 워크스페이스 전용입니다. |

### Upwork

Upwork 에이전트의 도구입니다. 공개 일감을 읽고, 점수를 매기고, 워크스페이스 지식 베이스를 바탕으로 답안을 작성합니다. Upwork로는 아무것도 전송되지 않습니다.

| 도구 | 유형 | 스코프 | 역할 |
| --- | --- | --- | --- |
| [`searchUpworkJobs`](/ko/docs/api/reference/upwork#searchupworkjobs) | 실시간 읽기 | `explore` | 공개 결과 한 페이지(일감 약 10건)를 읽고 각 일감을 지식 베이스와 비교해 점수를 매깁니다. 일감은 워크스페이스 파이프라인에 추가됩니다. |
| [`getUpworkJob`](/ko/docs/api/reference/upwork#getupworkjob) | 실시간 읽기 | `explore` | 일감을 읽습니다: 설명, 기술, 예산, 활동, 클라이언트. 날짜가 있는 스냅샷을 파이프라인에 추가합니다. |
| [`scoreUpworkJobs`](/ko/docs/api/reference/upwork#scoreupworkjobs) | 쓰기 | `write` | 지식 베이스가 바뀐 후 파이프라인 일감의 점수를 다시 매깁니다. 페이지는 읽지 않습니다. |
| [`getUpworkRadar`](/ko/docs/api/reference/upwork#getupworkradar) | 실시간 읽기 | `explore` | 시장 레이더: 일별 건수, 요율과 예산의 사분위수, 기술, 경쟁, 클라이언트 국가. |
| [`listUpworkLeads`](/ko/docs/api/reference/upwork#listupworkleads) | 읽기 | `read` | Upwork 파이프라인: 상태별 건수, 우수 일감 순, 각 일감의 결과. |
| [`updateUpworkLead`](/ko/docs/api/reference/upwork#updateupworklead) | 쓰기 | `write` | 파이프라인 일감의 상태(발송, 답장, 인터뷰, 수주, 실패, 무시)를 변경하고 메모를 남깁니다. |
| [`getUpworkKnowledge`](/ko/docs/api/reference/upwork#getupworkknowledge) | 읽기 | `read` | 워크스페이스의 Upwork 지식 베이스: 서비스, 도구, 피할 프로젝트, 최저 요율, 사례, 어조, 서명. |
| [`updateUpworkKnowledge`](/ko/docs/api/reference/upwork#updateupworkknowledge) | 쓰기 | `write` | 지식 베이스를 업데이트합니다. 보낸 목록은 저장된 목록을 대체합니다. |
| [`listUpworkTemplates`](/ko/docs/api/reference/upwork#listupworktemplates) | 읽기 | `read` | 저장된 제안서 템플릿과 슬롯, 질문 규칙. |
| [`upsertUpworkTemplate`](/ko/docs/api/reference/upwork#upsertupworktemplate) | 쓰기 | `write` | 제안서 템플릿을 만들거나 업데이트합니다. |
| [`draftUpworkProposal`](/ko/docs/api/reference/upwork#draftupworkproposal) | 쓰기 | `write`, `explore` | 템플릿으로 일감에 대한 제안서 초안을 작성합니다. 텍스트는 직접 Upwork에 붙여 넣습니다. |
| [`listUpworkCampaigns`](/ko/docs/api/reference/upwork#listupworkcampaigns) | 읽기 | `read` | 저장된 캠페인: 검색, 최소 점수, 상태, 마지막 새로고침, 소스 상태. |
| [`saveUpworkCampaign`](/ko/docs/api/reference/upwork#saveupworkcampaign) | 쓰기 | `write` | 캠페인을 만들거나 업데이트합니다: 이름, 검색, 최소 점수, 템플릿. |
| [`simulateUpworkCampaign`](/ko/docs/api/reference/upwork#simulateupworkcampaign) | 실시간 읽기 | `explore` | 팔로우하기 전에 실제 일감으로 캠페인을 시뮬레이션합니다. 아무것도 저장되지 않습니다. |
| [`followUpworkCampaign`](/ko/docs/api/reference/upwork#followupworkcampaign) | 실행 | `act` | 저장된 캠페인을 수집 주기에 맞춰 팔로우하도록 Motor에 요청합니다. |
| [`pauseUpworkCampaign`](/ko/docs/api/reference/upwork#pauseupworkcampaign) | 실행 | `act` | Motor가 캠페인을 팔로우하지 않도록 중지합니다. 이미 본 일감은 파이프라인에 남습니다. |
| [`refreshUpworkCampaigns`](/ko/docs/api/reference/upwork#refreshupworkcampaigns) | 쓰기 | `write`, `explore` | 팔로우 중인 캠페인을 새로고침합니다: Motor가 수집한 일감을 병합하고, 첫 페이지를 실시간으로 다시 읽고, 새 일감의 점수를 매깁니다. |
| [`checkUpworkOutcomes`](/ko/docs/api/reference/upwork#checkupworkoutcomes) | 쓰기 | `write`, `explore` | 진행 중인 지원 페이지를 다시 읽어 결과 날짜를 기록합니다: 마감, 인터뷰 시작, 무응답. |
| [`syncUpworkReplies`](/ko/docs/api/reference/upwork#syncupworkreplies) | 쓰기 | `write` | 키를 만든 사람이 연결한 받은편지함에서 Upwork 알림 이메일을 읽고 파이프라인 일감의 상태를 진행시킵니다. |

### 워크스페이스에 쓰기

워크스페이스 객체를 만들거나 변경하는 Piqline 에이전트의 도구입니다. `write` 스코프가 필요합니다.

| 도구 | 유형 | 스코프 | 역할 |
| --- | --- | --- | --- |
| [`updateWorkspaceProfile`](/ko/docs/api/reference/write#updateworkspaceprofile) | 쓰기 | `write` | 워크스페이스의 니즈 프로필을 저장합니다: 목표, 주제, 엔티티, 언어, 지역, 수준, 속도. |
| [`followEntity`](/ko/docs/api/reference/write#followentity) | 쓰기 | `write` | 회사, 브랜드 또는 공개 계정(개인은 제외)을 팔로우하여 그 항목과 언급을 연결합니다. |
| [`unfollowEntity`](/ko/docs/api/reference/write#unfollowentity) | 삭제 | `write` | 엔티티 팔로우를 중단합니다. 기존 연결은 남습니다. |
| [`saveBookmark`](/ko/docs/api/reference/write#savebookmark) | 쓰기 | `write` | 워크스페이스 보관함에 북마크를 저장합니다. http(s) URL은 읽기, 보관, 벡터화 대기열에 들어갑니다. |
| [`setWatchContract`](/ko/docs/api/reference/write#setwatchcontract) | 쓰기 | `write` | 소스에 모니터링 계약을 설정합니다. 이후 모니터링 페이지에는 일치하는 항목만 표시됩니다. 결정적 방식이며 모델을 사용하지 않습니다. |
| [`removeWatchContract`](/ko/docs/api/reference/write#removewatchcontract) | 삭제 | `write` | 소스의 모니터링 계약을 제거합니다. 모든 항목이 다시 표시됩니다. |
| [`initReaderInterview`](/ko/docs/api/reference/write#initreaderinterview) | 쓰기 | `write` | 읽기 인터뷰의 두 가지 답(핵심 또는 상세, 주된 의도)을 읽기 프로필에 저장합니다. |
| [`applyBoardChange`](/ko/docs/api/reference/write#applyboardchange) | 쓰기 | `write` | 이미 승인된 변경 사항을 보드에 적용합니다. |
| [`buildDashboard`](/ko/docs/api/reference/write#builddashboard) | 쓰기 | `write` | 위젯 선택기를 거치지 않고 보드를 직접 만듭니다. |
| [`saveWorkspaceTable`](/ko/docs/api/reference/write#saveworkspacetable) | 쓰기 | `write` | 유용한 열이 채워진 워크스페이스 테이블을 만듭니다. |
| [`writeFromWatch`](/ko/docs/api/reference/write#writefromwatch) | 쓰기 | `write` | 워크스페이스 모니터링 항목을 바탕으로 텍스트를 작성합니다(기사, LinkedIn 게시물, X 스레드, Instagram 캡션, 뉴스레터, 동영상 스크립트, 보도 자료, SEO 기사, 이메일, 요약). 9개 언어를 지원하며, 각 사실에는 출처를 [n]으로 인용하고, 텍스트는 초안에 추가됩니다. 크레딧을 조금 사용합니다. |
| [`setTableFeed`](/ko/docs/api/reference/write#settablefeed) | 실행 | `act`, `write` | 테이블이 스스로 채워지게 합니다: 규칙에 맞는 코퍼스 항목이 생기면 확인 후 추가됩니다. status=paused는 채우기를 중지합니다. |

### 소스와 규칙에 대한 실행

Piqline 에이전트의 실행 도구입니다. 채팅에서는 각 도구가 확인을 요청합니다. API에서는 `act` 스코프로 직접 호출하는 것이 확인으로 간주됩니다. 해당하는 사람이 동의한 후에만 이 도구를 호출하십시오.

| 도구 | 유형 | 스코프 | 역할 |
| --- | --- | --- | --- |
| [`subscribeSource`](/ko/docs/api/reference/act#subscribesource) | 실행 | `act` | 새 소스를 구독합니다. 실제 수집(읽기 작업, 플랫폼 쿼터)을 시작합니다. |
| [`subscribeSources`](/ko/docs/api/reference/act#subscribesources) | 실행 | `act` | 한 번의 호출로 여러 소스를 구독하고 소스별 결과를 반환합니다. |
| [`unsubscribeSource`](/ko/docs/api/reference/act#unsubscribesource) | 실행 | `act` | 소스 팔로우를 중단합니다. 이미 수집된 항목은 코퍼스에 남습니다. |
| [`setHomeDashboard`](/ko/docs/api/reference/act#sethomedashboard) | 실행 | `act` | 저장된 보드를 워크스페이스 홈으로 설정합니다. |
| [`upsertSignalRule`](/ko/docs/api/reference/act#upsertsignalrule) | 실행 | `act` | 지속성 신호 규칙을 만들거나 업데이트합니다. 항목이 임계값보다 오래 온라인에 남아 있으면 발동합니다. |
| [`upsertQuestionRule`](/ko/docs/api/reference/act#upsertquestionrule) | 실행 | `act` | 상시 질문을 만들거나 업데이트합니다. 워크스페이스 소스의 모든 새 항목에 대해 Jev가 던지는 평이한 문장입니다. 확률 임계값이 신호를 만듭니다. |
| [`startInvestigation`](/ko/docs/api/reference/act#startinvestigation) | 실행 | `act` | 이 워크스페이스를 위한 백그라운드 Edge 조사를 대기열에 넣습니다(소유자 또는 관리자). |
| [`startHunt`](/ko/docs/api/reference/act#starthunt) | 실행 | `act` | 헌트를 시작합니다. 검증 가능한 조건을 충족하는 사람을 찾으며, 각 조건은 날짜가 있는 공개 출처로 입증됩니다. 민감한 조건은 거부되고 연락처는 반환되지 않습니다. 백그라운드에서 실행되며 해당 월의 크레딧을 사용합니다. 소유자 또는 관리자. |
| [`buildAdAudit`](/ko/docs/api/reference/act#buildadaudit) | 쓰기 | `write` | 이미 수집된 광고주 1~6곳의 캠페인을 N개월에 걸쳐 소급 감사합니다. 워크스페이스 테이블(광고주, 월, 신규 광고, 중단, 라이브러리, 국가, 읽은 니즈, 증가)과 인용된 요약의 수치를 만듭니다. 크레딧을 사용하지 않습니다. |
| [`findCreatorSponsors`](/ko/docs/api/reference/act#findcreatorsponsors) | 실행 | `act`, `write`, `explore` | 특정 분야에서 YouTube 크리에이터에게 비용을 지불하는 곳: 최근 동영상을 검색하고, 각 동영상에서 스폰서를 추론하여 “Sponsors · niche” 워크스페이스 테이블을 만듭니다. 크레딧을 사용하며, 채팅에서 확인을 거치고, 소유자 또는 관리자 전용입니다. |
| [`importAdHistory`](/ko/docs/api/reference/act#importadhistory) | 실행 | `act`, `write`, `explore` | 광고주 수집의 Google 이력을 가져옵니다. 최대 20페이지(2021년 이후 광고 약 800건)로 과거 캠페인의 날짜를 파악합니다. 크레딧을 사용하며, 채팅에서 확인을 거치고, 소유자 또는 관리자 전용입니다. |
| [`startAdCollection`](/ko/docs/api/reference/act#startadcollection) | 실행 | `act`, `write`, `explore` | 광고주(이름 또는 도메인) 또는 키워드에 대한 광고 수집을 시작합니다. Meta, TikTok, Google, LinkedIn을 읽고 모든 광고를 같은 형식으로 정리한 다음 각도, 오퍼, 타겟, 어조를 읽습니다. 크레딧을 사용하며, 채팅에서 확인을 거치고, 소유자 또는 관리자 전용입니다. |
