跳到正文

指南

工具

逐个调用智能体的工具,了解它们的 scope 和输入。

Piqline 的智能体依靠工具工作:读取语料库、实时搜索、写入、执行操作。API 以统一的形式开放每一个工具。共有 92 个可调用工具;工具目录列出它们及其 scope,参考描述每个工具的参数,并附调用示例。

列出工具#

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所需的 scope
callable你的密钥能否调用它,true 表示可以
missing_scopes密钥缺少的 scope
confirmation_in_chattrue 表示聊天会在工具运行前请求确认
read_onlytrue 表示该工具不修改任何内容
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。没有输入的工具接受空请求体。

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}'

响应包含工具名及其输出,与智能体读到的输出相同:

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 scope 的直接调用会立即执行。
  • 实时读取会消耗积分。 explore scope 的工具从工作区的每月上限中扣除积分。

工具目录#

读取语料库和工作区#

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读取readUpwork 管道:各状态的数量、最佳职位在前、每个职位的结果。
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,把每条广告统一为相同格式,然后判读角度、优惠、受众和语气。会消耗积分;在聊天中需确认,所有者或管理员。

对 API 有疑问,或发现本页有误? 联系我们.