ガイド
ツール
エージェントのツールを 1 つずつ、スコープと入力を確認しながら呼び出します。
Piqline のエージェントはツールで動作します。コーパスの読み取り、ライブ検索、書き込み、アクションがあります。API は、そのすべてを同じ形式で公開しています。呼び出せるツールは 92 個です。カタログにスコープ付きで一覧があり、リファレンスに各ツールのパラメーターと呼び出し例があります。
ツールを一覧する#
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} は、1 つのツールについて同じ項目を返しますが、confirmation_in_chat と read_only は含みません。
ツールを呼び出す#
POST https://piqline.com/api/v1/tools/{nom}
Content-Type: application/jsonJSON の本文が、input_schema の定める形式のツール入力になります。入力のないツールは、空の本文を受け付けます。
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}'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();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()レスポンスにはツール名とその出力が入ります。エージェントが読むのと同じ出力です。
{
"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 で返されます。エラーを参照してください。
誰が何を呼び出せるか#
- キーの範囲は作成者のロールで決まります。 そのロールが開いていないツールは
403 forbiddenを返します。書き込みツール、アクションツール、onboardingエージェントは、オーナーと管理者に限られます。 - チャットのカードは API にありません。
askUser、proposeSources、proposeBoardなどは、人に表示するためのもので、何も実行しません。404 not_foundを返します。この対話が必要な場合は、エージェントを実行してください。 - アクションツールは確認を待ちません。 チャットは確認を求めますが、
actスコープでの直接呼び出しはすぐに実行されます。 - ライブ読み取りはクレジットを使います。
exploreスコープのツールは、ワークスペースの月間上限からクレジットを消費します。
カタログ#
コーパスとワークスペースを読む#
Piqline エージェントのツールです。ワークスペースがすでに収集した内容を読み取ります。クレジットは使わず、何も書き込みません。
| ツール | 種類 | スコープ | 役割 |
|---|---|---|---|
getCoverageStats | 読み取り | read | 収集量とその状態。合計、プラットフォーム別と種類別の内訳、分析期間(1h、24h、7d、30d)の取り込み推移。 |
listSources | 読み取り | read | ワークスペースが追跡しているソース。アイテム数、状態、最終読み取りを含みます。 |
searchItems | 読み取り | read | アイテム(投稿、動画、記事、広告、求人)を、テキスト、プラットフォーム、種類、ソースで絞り込んで検索します。絞り込みがない場合は、最新のアイテムを返します(最大 40 件)。 |
getItem | 読み取り | read | アイテムの詳細。テキスト、文字起こし、OCR、検出されたトピック、意味の近いアイテム、観測日。 |
searchPassages | 読み取り | read | 長い文書(Motor が読み取った PDF)を意味で検索します。質問に最も近い箇所を、アイテム、ページ、セクション見出しとともに返します。 |
citeItem | 読み取り | read | ある箇所がアイテム内に一字一句そのまま存在することを確認し、引用番号を返します。存在しない場合は、最も近い箇所を返します。チャットの引用モードの基盤です。 |
drawDiagram | 読み取り | read | 回答を SVG の図(タイムライン、マトリクス、フロー、ツリーなど)として描画します。色はテーマのロールに従い、SVG は表示前にサニタイズされます。チャットの図モードの基盤です。 |
createCanvas | 読み取り | read | キャンバス(piqline/canvas SDK だけをインポートする TSX ファイル)をコンパイルし、表示可能なコード、または修正すべきエラーを返します。チャットのキャンバスモードとレポートモードの基盤です。 |
getTopics | 読み取り | read | 検出されたトピックと発言シェア、およびストーリー(複数のソースで見られる同じ話題)。 |
getSignals | 読み取り | read | ワークスペースの継続ルールによって発火した、未解決のシグナル。リードタイムとステータス付き。 |
listWorkspaceTables | 読み取り | read | ワークスペースに作成済みのテーブル。名前、コメント、列数と行数、テーブルが自動で埋まるかどうか。 |
getWorkspaceTable | 読み取り | read | ワークスペースのテーブルを JSON で返します。スキーマ、列、行を含みます。サイト、アプリ、エージェントの土台やフィードとして使えます(read スコープ)。 |
listBookmarks | 読み取り | read | ワークスペースのヴォールトにあるブックマークとフォルダー。タイトル、種類、フォルダー、ステータス、受け入れ状況。単語、ステータス、種類での絞り込みも可能です。 |
listEntities | 読み取り | read | 追跡中のエンティティ(企業、ブランド、公開アカウント)と、期間内に関連付けられたアイテム。 |
listWatchContracts | 読み取り | read | ソースに設定されたウォッチ契約。意図、残す語と除外する語、イベント。 |
checkInvestigation | 読み取り | read | 最新の Edge 調査、または指定した調査のステータス。保留中、実行中、候補付きの完了、失敗のいずれか。 |
checkHunt | 読み取り | read | 最新のハント、または指定したハントのステータス。段階、見つかった人物(コードの判定とあなたの判定)、各条件のステータスと日付付きの公開証拠(URL、日付、抜粋)。連絡先は返しません。 |
planSourcePack | 読み取り | read | 目的に合わせて、追跡するソースのまとまりを提案します。何も作成しません。 |
listWidgets | 読み取り | read | このワークスペースのボードに置けるウィジェット。利用者に合わせて順位付けし、理由を添えます。 |
getAdvertiserCampaigns | 読み取り | read | ワークスペースの収集結果から得た広告主の広告ファイル。広告、配信中の広告、日付、ライブラリ、国、読み取ったニーズ、月ごとの新規広告とランプアップ、最新の広告、シグナル。人物は対象外です。クレジットは使いません。 |
listAdSignals | 読み取り | read | ワークスペースの広告シグナル(1 時間ごとに計算)。キャンペーンの開始と停止、ランプアップ、新しい国、新しいプラットフォーム、有料の求人、プロモーション、ローンチ、新しい広告主。クレジットは使いません。 |
listCollectedAds | 読み取り | read | ワークスペースで収集済みの広告コレクション(Meta、TikTok、Google、LinkedIn)。一覧を返します。コレクション名を指定すると、その内訳(切り口、オファー、トーン、フォーマット)、ペース、最も長く配信されている広告、ライブラリ、ステータス、切り口、単語で絞り込んだ広告を返します。クレジットは使いません。 |
Web とレジストリをライブで調べる#
Web と公開ネットワークのライブ読み取りです。クレジットを使います。ワークスペースには何も保存されません。
| ツール | 種類 | スコープ | 役割 |
|---|---|---|---|
readPage | ライブ読み取り | explore | 公開 Web ページを読み取ります。タイトル、本文(6,000 文字)、検出したフィード、30 件のリンク。 |
searchWeb | ライブ読み取り | explore | 公開 Web を検索して、候補となる URL を見つけます。 |
browserRead | ライブ読み取り | explore | 動的ページや保護されたページを、ブラウザーを強制して読み取ります。形式は readPage と同じです。 |
waybackHistory | ライブ読み取り | explore | URL の Wayback Machine でのキャプチャ。最初のキャプチャと最近のキャプチャ。 |
registryLookup | ライブ読み取り | explore | 公開レジストリで企業を検索します。Sirene(フランス)、EDGAR(米国)、Companies House(英国)、OpenCorporates。 |
socialCatalog | ライブ読み取り | explore | SNS の読み取りエンドポイントを一覧します(最大 40 件)。プラットフォームで絞り込めます。 |
socialCall | ライブ読み取り | explore | SNS の読み取りエンドポイントを呼び出し、簡略化したアイテムを最大 20 件返します。 |
previewSource | ライブ読み取り | explore | 購読する前に、ソースのライブサンプル(5〜10 件)を取得します。 |
whoSaidItFirst | ライブ読み取り | explore | ある情報を Web 上で最初に公開したのは誰か、ページごとに調べ、あなたのソースがそれをいつ確認したかを示します。話題またはアイテムから開始し、ワークスペース専用のタイムラインとして保存されます。 |
Facebook#
Facebook エージェントのツールです。Marketplace の出品と公開グループをライブで読み取ります。
| ツール | 種類 | スコープ | 役割 |
|---|---|---|---|
findMarketplaceLocation | ライブ読み取り | explore | 都市または地域の名前を、Marketplace の座標に変換します。 |
searchMarketplace | ライブ読み取り | explore | ある場所(都市または座標)の周辺で、キーワードにより Marketplace の公開出品を検索します。最大 3 ページ。 |
getMarketplaceListing | ライブ読み取り | explore | 出品の詳細。説明、属性、写真、配送、Facebook が提供する場合は正確な日付。 |
getMarketplaceListings | ライブ読み取り | explore | 2〜6 件の出品の詳細を、比較表としてまとめて取得します。 |
getFacebookGroup | ライブ読み取り | explore | 公開グループのプロフィール。プライバシー設定、規模、活動、カテゴリ、ルール。 |
getFacebookGroupPosts | ライブ読み取り | explore | 公開グループの投稿を、3 件ずつのページで取得します(最大 6 ページ)。 |
getFacebookPost | ライブ読み取り | explore | 公開投稿またはリールの詳細。テキスト、投稿者、日付、リアクション、再生数。 |
getFacebookPostComments | ライブ読み取り | explore | 公開投稿のコメントを、キーワードで絞り込んで取得します(最大 3 ページ)。 |
LinkedIn#
LinkedIn エージェントのツールです。公開投稿、企業ページ、広告をライブで読み取ります。連絡先は読み取りません。
| ツール | 種類 | スコープ | 役割 |
|---|---|---|---|
searchLinkedinPosts | ライブ読み取り | explore | キーワードで公開投稿をリアルタイムに検索し、新しい順に返します(一部しか読めなかった場合は結果に明示されます)。求人の投稿には投稿者の肩書きとロールが付き、コードで算出したシグナルも付きます。採用、資金調達、ローンチ、拡大、組織再編、稼働可能、退職。 |
probeLinkedinWatch | ライブ読み取り | explore | LinkedIn ウォッチを購読する前に、1〜3 個のクエリ案を試し、購読に添付する調査チケットを返します。 |
getLinkedinPost | ライブ読み取り | explore | 公開投稿または記事を読み取ります。テキスト、投稿者、日付、リアクション、シグナル付きのコメント。 |
getLinkedinPostTranscript | ライブ読み取り | explore | 公開投稿の動画の文字起こし。存在する場合にのみ課金されます。 |
getLinkedinCompany | ライブ読み取り | explore | 公開された企業ページ。説明、従業員数、業種、資金調達、シグナル付きの最新投稿。 |
getLinkedinCompanyPosts | ライブ読み取り | explore | 企業ページの過去の投稿と、シグナル(採用、資金調達、ローンチ)の要約。 |
searchLinkedinAds | ライブ読み取り | explore | 広告ライブラリを検索します。広告主、フォーマット、日付、インプレッション。 |
getLinkedinAd | ライブ読み取り | explore | ライブラリにある広告の詳細。ターゲティング、国別インプレッション、配信期間。 |
matchLinkedinPosts | ライブ読み取り | explore | 公開投稿をもとに、対応可能な人と案件を照合します(2 回の検索)。 |
getLinkedinProfile | ライブ読み取り | explore | 公開された /in/ プロフィールを、範囲を限って読み取ります。その人物に言及した公開投稿から辿る場合に限ります。このオプションを有効にしたワークスペース専用です。 |
Upwork#
Upwork エージェントのツールです。公開された案件を読み取り、スコアを付け、ワークスペースのナレッジベースをもとに回答を作成します。Upwork には何も送信しません。
| ツール | 種類 | スコープ | 役割 |
|---|---|---|---|
searchUpworkJobs | ライブ読み取り | explore | 公開結果の 1 ページ(約 10 件の案件)を読み取り、ナレッジベースに照らして各案件にスコアを付けます。案件はワークスペースのパイプラインに追加されます。 |
getUpworkJob | ライブ読み取り | explore | 案件を読み取ります。説明、スキル、予算、アクティビティ、クライアント。日付付きのスナップショットをパイプラインに追加します。 |
scoreUpworkJobs | 書き込み | write | ナレッジベースを変更した後に、パイプラインの案件を再スコアリングします。ページは読み取りません。 |
getUpworkRadar | ライブ読み取り | explore | 市場レーダー。日ごとの件数、単価と予算の四分位、スキル、競合状況、クライアントの国。 |
listUpworkLeads | 読み取り | read | Upwork のパイプライン。ステータスごとの件数、上位の案件、各案件の結果。 |
updateUpworkLead | 書き込み | write | パイプラインの案件のステータス(送信済み、返信、面談、受注、失注、無視)を変更し、メモを残します。 |
getUpworkKnowledge | 読み取り | read | ワークスペースの Upwork ナレッジベース。サービス、ツール、避けたい案件、最低単価、事例、トーン、署名。 |
updateUpworkKnowledge | 書き込み | write | ナレッジベースを更新します。送信したリストは、保存済みのリストを置き換えます。 |
listUpworkTemplates | 読み取り | read | 保存済みの提案テンプレート。スロットと質問ルール付き。 |
upsertUpworkTemplate | 書き込み | write | 提案テンプレートを作成または更新します。 |
draftUpworkProposal | 書き込み | write, explore | テンプレートをもとに、案件への提案文を下書きします。Upwork へは自分で貼り付けます。 |
listUpworkCampaigns | 読み取り | read | 保存済みのキャンペーン。検索、最低スコア、ステータス、最終更新、ソースの状態。 |
saveUpworkCampaign | 書き込み | write | キャンペーンを作成または更新します。名前、検索、最低スコア、テンプレート。 |
simulateUpworkCampaign | ライブ読み取り | explore | 追跡を始める前に、実際の案件でキャンペーンをシミュレーションします。何も保存しません。 |
followUpworkCampaign | アクション | act | 保存済みのキャンペーンを、その収集ペースで追跡するよう Motor に依頼します。 |
pauseUpworkCampaign | アクション | act | Motor によるキャンペーンの追跡を止めます。すでに確認した案件はパイプラインに残ります。 |
refreshUpworkCampaigns | 書き込み | write, explore | 追跡中のキャンペーンを更新します。Motor が収集した案件を統合し、最初のページをライブで再度読み取り、新しい案件にスコアを付けます。 |
checkUpworkOutcomes | 書き込み | write, explore | 進行中の応募のページを再度読み取り、結果の日付を記録します。クローズ、面談の開始、返信なし。 |
syncUpworkReplies | 書き込み | write | キー作成者の接続済み受信トレイにある Upwork の通知メールを読み取り、パイプラインの案件のステータスを進めます。 |
ワークスペースに書き込む#
ワークスペースのオブジェクトを作成または変更する、Piqline エージェントのツールです。write スコープが必要です。
| ツール | 種類 | スコープ | 役割 |
|---|---|---|---|
updateWorkspaceProfile | 書き込み | write | ワークスペースのニーズプロファイルを保存します。目的、テーマ、エンティティ、言語、地域、レベル、ペース。 |
followEntity | 書き込み | write | 企業、ブランド、公開アカウント(個人は対象外)を追跡し、そのアイテムと言及を関連付けます。 |
unfollowEntity | 削除 | write | エンティティの追跡を止めます。既存の関連付けは残ります。 |
saveBookmark | 書き込み | write | ワークスペースのヴォールトにブックマークを保存します。http(s) の URL は、読み取り、アーカイブ、ベクトル化のキューに入ります。 |
setWatchContract | 書き込み | write | ソースにウォッチ契約を設定します。以後、ウォッチのページには条件に合うアイテムだけが表示されます。決定的な処理で、モデルは使いません。 |
removeWatchContract | 削除 | write | ソースのウォッチ契約を削除します。すべてのアイテムが再び表示されます。 |
initReaderInterview | 書き込み | write | 読み方のインタビューの 2 つの回答(要点か詳細か、主な意図)を、閲覧プロファイルに保存します。 |
applyBoardChange | 書き込み | write | すでに承認された変更を、ボードに適用します。 |
buildDashboard | 書き込み | write | ウィジェットの選択画面を経由せず、ボードを直接作成します。 |
saveWorkspaceTable | 書き込み | write | ワークスペースのテーブルを、必要な列を入れた状態で作成します。 |
writeFromWatch | 書き込み | write | ワークスペースのウォッチにあるアイテムから文章を作成します(記事、LinkedIn 投稿、X のスレッド、Instagram のキャプション、ニュースレター、動画の台本、プレスリリース、SEO 記事、メール、要約)。9 言語に対応し、すべての事実に出典を [n] で付けます。文章は下書きに追加されます。少量のクレジットを使います。 |
setTableFeed | アクション | act, write | テーブルを自動で更新するようにします。ルールに合うコーパスのアイテムがあれば、確認の後で追加されます。status=paused で追加を止めます。 |
ソースとルールを操作する#
Piqline エージェントのアクションツールです。チャットでは、いずれも確認を求めます。API では、act スコープでの直接呼び出しが確認とみなされます。これらのツールは、当事者の同意を得てから呼び出してください。
| ツール | 種類 | スコープ | 役割 |
|---|---|---|---|
subscribeSource | アクション | act | 新しいソースを購読します。実際の収集(読み取りジョブ、プラットフォームのクォータ)が始まります。 |
subscribeSources | アクション | act | 複数のソースを 1 回の呼び出しで購読し、ソースごとに 1 つの結果を返します。 |
unsubscribeSource | アクション | act | ソースの追跡を止めます。すでに収集したアイテムはコーパスに残ります。 |
setHomeDashboard | アクション | act | 保存済みのボードを、ワークスペースのホームに設定します。 |
upsertSignalRule | アクション | act | 継続シグナルのルールを作成または更新します。アイテムがしきい値より長くオンラインに残ると発火します。 |
upsertQuestionRule | アクション | act | 定期質問を作成または更新します。ワークスペースのソースに届く新しいアイテムごとに、Jev に投げかける平易な文です。確率のしきい値がシグナルを決めます。 |
startInvestigation | アクション | act | このワークスペースのバックグラウンド Edge 調査をキューに入れます(オーナーまたは管理者)。 |
startHunt | アクション | act | ハントを開始します。検証可能な条件を満たす人物を探し、各条件を日付付きの公開ソースで裏付けます。機微な条件は拒否され、連絡先は返しません。バックグラウンドで実行され、当月のクレジットを使います。オーナーまたは管理者。 |
buildAdAudit | 書き込み | write | すでに収集した 1〜6 社の広告主のキャンペーンを、N か月分さかのぼって監査します。ワークスペースのテーブル(広告主、月、新規広告、停止、ライブラリ、国、読み取ったニーズ、ランプアップ)と、出典付き要約の数値を返します。クレジットは使いません。 |
findCreatorSponsors | アクション | act, write, explore | あるニッチで YouTube クリエイターに報酬を支払っているのは誰か。最近の動画を検索し、各動画からスポンサーを推定して、ワークスペースのテーブル「Sponsors · niche」を作成します。クレジットを使います。チャットでは確認が必要で、オーナーまたは管理者。 |
importAdHistory | アクション | act, write, explore | 広告主コレクションの Google 履歴をインポートします。最大 20 ページ(2021 年以降の約 800 件の広告)で、過去のキャンペーンの日付を特定します。クレジットを使います。チャットでは確認が必要で、オーナーまたは管理者。 |
startAdCollection | アクション | act, write, explore | 広告主(名前またはドメイン)またはキーワードの広告収集を開始します。Meta、TikTok、Google、LinkedIn を読み取り、すべての広告を同じ形式にそろえ、切り口、オファー、オーディエンス、トーンを読み取ります。クレジットを使います。チャットでは確認が必要で、オーナーまたは管理者。 |