指南
工具
逐个调用智能体的工具,了解它们的 scope 和输入。
Piqline 的智能体依靠工具工作:读取语料库、实时搜索、写入、执行操作。API 以统一的形式开放每一个工具。共有 92 个可调用工具;工具目录列出它们及其 scope,参考描述每个工具的参数,并附调用示例。
列出工具#
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 | 所需的 scope |
callable | 你的密钥能否调用它,true 表示可以 |
missing_scopes | 密钥缺少的 scope |
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。
调用工具#
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。要获得这类对话,请运行智能体。 - 操作工具不会等待确认。 聊天中会请求确认。带有
actscope 的直接调用会立即执行。 - 实时读取会消耗积分。
explorescope 的工具从工作区的每月上限中扣除积分。
工具目录#
读取语料库和工作区#
Piqline 智能体的工具。它们读取工作区已经采集的内容:不消耗积分,不写入任何数据。
| 工具 | 类型 | Scope | 作用 |
|---|---|---|---|
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 scope)。 |
listBookmarks | 读取 | read | 工作区收藏库的书签和文件夹:标题、类型、文件夹、状态、收录情况。可按关键词、状态或类型筛选。 |
listEntities | 读取 | read | 已关注的实体(公司、品牌、公开账号),以及该时段内关联的条目。 |
listWatchContracts | 读取 | read | 为来源设置的监控合约:意图、保留和排除的词、事件。 |
checkInvestigation | 读取 | read | 最近一次 Edge 调查或指定调查的状态:等待中、运行中、已完成(附候选结果)或失败。 |
checkHunt | 读取 | read | 最近一次搜寻或指定搜寻的状态:阶段、找到的人员(附代码的判定和你的判定),以及每项标准的状态及其带日期的公开证据(URL、日期、摘录)。从不包含联系方式。 |
planSourcePack | 读取 | read | 针对某个目标,提出一组协调一致的待关注来源。不创建任何内容。 |
listWidgets | 读取 | read | 可放入此工作区看板的组件,按对用户的相关度排序,并附理由。 |
getAdvertiserCampaigns | 读取 | read | 来自工作区采集的广告主广告档案:广告、在投广告、日期、广告库、国家、已读取的需求、每月新增广告和投放放量、最新广告、信号。从不针对个人。不消耗积分。 |
listAdSignals | 读取 | read | 工作区的广告信号,每小时计算一次:投放开始或停止、放量、新国家、新平台、付费招聘、促销、发布、新广告主。不消耗积分。 |
listCollectedAds | 读取 | read | 工作区中已读取的广告采集(Meta、TikTok、Google、LinkedIn):列出采集;若给出采集名称,则返回其细分(角度、优惠、语气、形式)、节奏、投放最久的广告,以及按广告库、状态、角度或关键词筛选的广告。不消耗积分。 |
实时探索网络和注册库#
对网络和公开网络的实时读取。它们会消耗积分;不会在工作区中存储任何内容。
| 工具 | 类型 | Scope | 作用 |
|---|---|---|---|
readPage | 实时读取 | explore | 读取公开网页:标题、正文主体(6,000 个字符)、发现的订阅源和 30 个链接。 |
searchWeb | 实时读取 | explore | 搜索公开网络,查找候选 URL。 |
browserRead | 实时读取 | explore | 用强制浏览器读取动态或受保护的页面。返回形式与 readPage 相同。 |
waybackHistory | 实时读取 | explore | 某个 URL 的 Wayback Machine 快照:首次快照和近期快照。 |
registryLookup | 实时读取 | explore | 在公开注册库中查询公司:Sirene(法国)、EDGAR(美国)、Companies House(英国)或 OpenCorporates。 |
socialCatalog | 实时读取 | explore | 列出社交网络的读取端点(最多 40 个),可按平台筛选。 |
socialCall | 实时读取 | explore | 调用社交网络的读取端点,最多返回 20 条精简条目。 |
previewSource | 实时读取 | explore | 订阅前对来源的实时抽样(5 到 10 条)。 |
whoSaidItFirst | 实时读取 | explore | 谁最先在网络上发布了某条信息(逐页追溯),以及你的来源何时看到它。从一个主题或一个条目出发;保存为工作区的私有时间线。 |
Facebook#
Facebook 智能体的工具:实时读取 Marketplace 商品和公开群组。
| 工具 | 类型 | Scope | 作用 |
|---|---|---|---|
findMarketplaceLocation | 实时读取 | explore | 把城市或区域名称转换为 Marketplace 坐标。 |
searchMarketplace | 实时读取 | explore | 按关键词搜索某地(城市或坐标)周边的 Marketplace 公开商品,最多 3 页。 |
getMarketplaceListing | 实时读取 | explore | 商品详情:描述、属性、照片、配送,以及 Facebook 提供时的确切日期。 |
getMarketplaceListings | 实时读取 | explore | 一次获取 2 到 6 个商品的详情,以对比表格形式返回。 |
getFacebookGroup | 实时读取 | explore | 群组的公开资料:隐私设置、规模、活跃度、分类、规则。 |
getFacebookGroupPosts | 实时读取 | explore | 公开群组的帖子,每页 3 条(最多 6 页)。 |
getFacebookPost | 实时读取 | explore | 公开帖子或 Reel 的详情:文本、作者、日期、互动、观看数。 |
getFacebookPostComments | 实时读取 | explore | 公开帖子的评论,可按关键词筛选(最多 3 页)。 |
LinkedIn#
LinkedIn 智能体的工具:实时读取公开帖子、公司主页和广告。从不读取联系方式。
| 工具 | 类型 | Scope | 作用 |
|---|---|---|---|
searchLinkedinPosts | 实时读取 | explore | 按关键词实时搜索公开帖子,最新的在前(结果中会标明只读取了一部分);当帖子为招聘时,附作者的头衔和职位,并包含由代码计算的信号:招聘、融资、发布、扩张、重组、可用状态、离职。 |
probeLinkedinWatch | 实时读取 | explore | 在订阅 LinkedIn 监控之前,试探 1 到 3 个查询变体,并返回要附加到订阅上的调查票据。 |
getLinkedinPost | 实时读取 | explore | 读取公开帖子或文章:文本、作者、日期、互动、带信号的评论。 |
getLinkedinPostTranscript | 实时读取 | explore | 公开帖子中视频的转写,仅在转写存在时才计费。 |
getLinkedinCompany | 实时读取 | explore | 公开的公司主页:简介、人数、行业、融资、最新帖子及其信号。 |
getLinkedinCompanyPosts | 实时读取 | explore | 公司主页的较早帖子,附信号摘要(招聘、融资、发布)。 |
searchLinkedinAds | 实时读取 | explore | 搜索广告库:广告主、形式、日期、展示量。 |
getLinkedinAd | 实时读取 | explore | 广告库中某条广告的详情:定向、各国展示量、投放时长。 |
matchLinkedinPosts | 实时读取 | explore | 依据公开帖子,把可用的人员与机会匹配(两次搜索)。 |
getLinkedinProfile | 实时读取 | explore | 有边界地读取公开的 /in/ 个人主页,仅限从点名该人的公开帖子出发。仅限已开启此选项的工作区使用。 |
Upwork#
Upwork 智能体的工具:读取公开职位,并依据工作区知识库对其评分和答复。不会向 Upwork 发送任何内容。
| 工具 | 类型 | Scope | 作用 |
|---|---|---|---|
searchUpworkJobs | 实时读取 | explore | 读取一页公开结果(约十个职位),并对照知识库为每个职位评分。这些职位会加入工作区的管道。 |
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 scope。
| 工具 | 类型 | Scope | 作用 |
|---|---|---|---|
updateWorkspaceProfile | 写入 | write | 保存工作区的需求档案:目标、主题、实体、语言、地区、级别、节奏。 |
followEntity | 写入 | write | 关注一家公司、一个品牌或一个公开账号(绝不关注私人个体),以关联其条目和提及。 |
unfollowEntity | 删除 | write | 停止关注某个实体。已有的关联保留。 |
saveBookmark | 写入 | write | 把书签保存到工作区收藏库。http(s) URL 会进入队列,等待读取、归档和向量化。 |
setWatchContract | 写入 | write | 为来源设置监控合约:监控页面随后只显示匹配的条目。确定性规则,不使用模型。 |
removeWatchContract | 删除 | write | 移除来源的监控合约:所有条目重新显示。 |
initReaderInterview | 写入 | write | 把阅读访谈的两个答案(只看要点还是看细节、主要意图)保存到阅读档案中。 |
applyBoardChange | 写入 | write | 把已经批准的更改应用到看板。 |
buildDashboard | 写入 | write | 直接构建看板,不经过组件选择器。 |
saveWorkspaceTable | 写入 | write | 创建一个工作区表格,并填入有用的列。 |
writeFromWatch | 写入 | write | 根据工作区监控的条目撰写文本(文章、LinkedIn 帖子、X 串文、Instagram 配文、新闻简报、视频脚本、新闻稿、SEO 文章、电子邮件、摘要),支持九种语言,每个事实都以 [n] 标注来源;文本进入草稿。会消耗少量积分。 |
setTableFeed | 操作 | act, write | 让表格自动更新:一旦语料库中的条目符合规则,经确认后就会加入表格。status=paused 会停止填充。 |
对来源和规则执行操作#
Piqline 智能体的操作工具。在聊天中,每个工具都会请求确认。通过 API 时,带有 act scope 的直接调用即视为确认:只有在相关人员同意之后,才调用这些工具。
| 工具 | 类型 | Scope | 作用 |
|---|---|---|---|
subscribeSource | 操作 | act | 订阅一个新来源。会启动真正的采集(读取任务、平台配额)。 |
subscribeSources | 操作 | act | 一次调用订阅多个来源,并为每个来源返回一个结果。 |
unsubscribeSource | 操作 | act | 停止关注某个来源。已采集的条目保留在语料库中。 |
setHomeDashboard | 操作 | act | 把一个已保存的看板设为工作区首页。 |
upsertSignalRule | 操作 | act | 创建或更新持续性信号规则:当条目在线时间超过阈值时触发。 |
upsertQuestionRule | 操作 | act | 创建或更新常设问题:一句用日常语言写的话,Jev 会对工作区来源中的每个新条目提出这个问题。概率阈值决定信号。 |
startInvestigation | 操作 | act | 为此工作区把一项后台 Edge 调查加入队列(所有者或管理员)。 |
startHunt | 操作 | act | 启动搜寻:查找满足可验证标准的人员,每项标准都有带日期的公开来源作证。敏感标准会被拒绝,也不会返回联系方式。在后台运行,并消耗当月积分;所有者或管理员。 |
buildAdAudit | 写入 | write | 对已采集的 1 到 6 个广告主的投放活动做追溯审计,覆盖 N 个月:生成一张工作区表格(广告主、月份、新增广告、停投、广告库、国家、已读取的需求、放量)以及带引用的摘要所用的数字。不消耗积分。 |
findCreatorSponsors | 操作 | act, write, explore | 谁在某个细分领域赞助 YouTube 创作者:搜索近期视频,从每个视频推断赞助商,生成“赞助商 · 领域”工作区表格。会消耗积分;在聊天中需确认,所有者或管理员。 |
importAdHistory | 操作 | act, write, explore | 导入某个广告主采集的 Google 历史:最多 20 页(自 2021 年以来约 800 条广告),用于标注过往投放的日期。会消耗积分;在聊天中需确认,所有者或管理员。 |
startAdCollection | 操作 | act, write, explore | 针对某个广告主(名称或域名)或关键词启动广告采集:读取 Meta、TikTok、Google 和 LinkedIn,把每条广告统一为相同格式,然后判读角度、优惠、受众和语气。会消耗积分;在聊天中需确认,所有者或管理员。 |