Leitfäden
Tools
Die Tools der Agenten einzeln aufrufen, mit ihren Scopes und Eingaben.
Piqline-Agenten arbeiten mit Tools: den Korpus lesen, live suchen, schreiben, handeln. Die API stellt jedes davon in derselben Form bereit. 92 Tools sind aufrufbar. Der Katalog listet sie mit ihren Scopes auf, und die Referenz beschreibt die Parameter jedes Tools mit Aufrufbeispielen.
Tools auflisten#
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 akzeptiert all (Standard), piqline, requete, facebook, linkedin, upwork oder onboarding. Jedes Tool in der Liste enthält:
| Feld | Bedeutung |
|---|---|
name | der Name des Tools, wie Sie es aufrufen |
description | was das Tool tut, auf Englisch, so wie der Agent es liest |
agents | die Agenten, die das Tool haben |
requires | die erforderlichen Scopes |
callable | true, wenn Ihr Schlüssel es aufrufen kann |
missing_scopes | Scopes, die dem Schlüssel fehlen |
confirmation_in_chat | true, wenn der Chat vor der Ausführung des Tools um Bestätigung bittet |
read_only | true, wenn das Tool nichts ändert |
input_schema | JSON Schema der Eingabe |
Tools, die Ihr Schlüssel nicht aufrufen kann, bleiben in der Liste, mit callable: false und missing_scopes. GET/api/v1/tools/{nom} liefert denselben Eintrag für ein einzelnes Tool, ohne confirmation_in_chat und read_only.
Tool aufrufen#
POST https://piqline.com/api/v1/tools/{nom}
Content-Type: application/jsonDer JSON-Body ist die Eingabe des Tools, wie input_schema sie beschreibt. Ein Tool ohne Eingabe akzeptiert einen leeren Body.
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()Die Antwort enthält den Namen des Tools und seine Ausgabe, dieselbe Ausgabe, die der Agent liest:
{
"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 ist das Anzeigedatum des Items. getItem liefert zusätzlich detectedAt (von Piqline zuerst gesehen), lastSeenAt (zuletzt gesehen) und publishedAt.
Ein Fehler kommt als application/problem+json zurück: siehe Fehler.
Wer was aufrufen darf#
- Die Rolle des Erstellers begrenzt den Schlüssel. Ein Tool, das diese Rolle nicht öffnet, antwortet mit
403 forbidden. Schreib-Tools, Aktions-Tools und der Agentonboardingsind Ownern und Admins vorbehalten. - Chat-Karten gibt es in der API nicht.
askUser,proposeSources,proposeBoardund verwandte Tools werden einer Person angezeigt und führen nichts aus: Sie antworten mit404 not_found. Für diesen Dialog starten Sie einen Agenten. - Aktions-Tools warten nicht auf Bestätigung. Der Chat fragt danach. Ein direkter Aufruf mit dem Scope
actwird sofort ausgeführt. - Live-Lesezugriffe verbrauchen Credits. Tools mit dem Scope
explorebelasten das monatliche Limit des Workspace.
Katalog#
Korpus und Workspace lesen#
Tools des Piqline-Agenten. Sie lesen, was der Workspace bereits erfasst hat: keine Credits verbraucht, nichts geschrieben.
| Tool | Typ | Scopes | Rolle |
|---|---|---|---|
getCoverageStats | Lesen | read | Erfassungsvolumen und Zustand: Summen, aufgeteilt nach Plattform und Art, Erfassungsreihen über das Analysefenster (1h, 24h, 7d oder 30d). |
listSources | Lesen | read | Quellen, denen der Workspace folgt, mit Anzahl der Items, Zustand und letztem Lesevorgang. |
searchItems | Lesen | read | Sucht Items (Beiträge, Videos, Artikel, Anzeigen, Jobs) mit Filtern: Text, Plattform, Art, Quelle. Ohne Filter werden die neuesten geliefert (höchstens 40). |
getItem | Lesen | read | Detail eines Items: Text, Transkript, OCR, erkannte Themen, bedeutungsnahe Items und seine Beobachtungsdaten. |
searchPassages | Lesen | read | Bedeutungssuche in langen Dokumenten (vom Motor gelesene PDFs): die Passagen, die einer Frage am nächsten kommen, mit Item, Seite und Abschnittstitel. |
citeItem | Lesen | read | Prüft, ob eine Passage wörtlich in einem Item vorkommt, und liefert eine Zitatnummer; andernfalls die nächstliegende Passage. Grundlage des Modus Zitate im Chat. |
drawDiagram | Lesen | read | Zeichnet die Antwort als SVG-Diagramm (Zeitleiste, Matrix, Ablauf, Baum …): Farben nach Rolle im Theme, SVG vor der Anzeige bereinigt. Grundlage des Modus Diagramm im Chat. |
createCanvas | Lesen | read | Kompiliert ein Canvas (eine TSX-Datei, die nur das SDK piqline/canvas importiert) und liefert anzeigefertigen Code oder den zu behebenden Fehler. Grundlage der Modi Canvas und Bericht im Chat. |
getTopics | Lesen | read | Erkannte Themen mit ihrem Anteil an der Aufmerksamkeit und Stories (dasselbe Thema, gesehen in mehreren Quellen). |
getSignals | Lesen | read | Offene Signale, ausgelöst durch die Persistenzregeln des Workspace, mit Vorlaufzeit und Status. |
listWorkspaceTables | Lesen | read | Bereits im Workspace erstellte Tabellen: Name, Kommentar, Anzahl der Spalten und Zeilen und ob sich die Tabelle selbst füllt. |
getWorkspaceTable | Lesen | read | Eine Workspace-Tabelle als JSON: Schema, Spalten und Zeilen. Dient als Grundlage oder Datenquelle für eine Website, eine App oder einen Agenten (Scope read). |
listBookmarks | Lesen | read | Lesezeichen und Ordner des Workspace-Tresors: Titel, Typ, Ordner, Status, Aufnahme. Optionaler Filter nach Wort, Status oder Typ. |
listEntities | Lesen | read | Verfolgte Entitäten (Unternehmen, Marken, öffentliche Konten) und verknüpfte Items im Zeitraum. |
listWatchContracts | Lesen | read | Auf Quellen gesetzte Watch-Verträge: Absicht, behaltene und ausgeschlossene Begriffe, Ereignis. |
checkInvestigation | Lesen | read | Status der letzten Edge-Recherche oder einer bestimmten: ausstehend, laufend, abgeschlossen mit ihren Kandidaten oder fehlgeschlagen. |
checkHunt | Lesen | read | Status der letzten Suche oder einer bestimmten: Stufe, gefundene Personen mit dem Urteil des Codes und Ihrem, und je Kriterium sein Status und sein datierter öffentlicher Beleg (URL, Datum, Ausschnitt). Nie Kontaktdaten. |
planSourcePack | Lesen | read | Schlägt für ein Ziel einen stimmigen Satz von Quellen zum Verfolgen vor. Erstellt nichts. |
listWidgets | Lesen | read | Widgets, die auf ein Board dieses Workspace gelegt werden können, für die Person gereiht, mit ihren Gründen. |
getAdvertiserCampaigns | Lesen | read | Anzeigenakte eines Werbetreibenden aus den Erfassungen des Workspace: Anzeigen, laufende, Daten, Bibliotheken, Länder, gelesene Bedarfe, neue Anzeigen pro Monat und Hochfahren, neueste Anzeigen, Signale. Nie eine Person. Keine Credits. |
listAdSignals | Lesen | read | Anzeigensignale des Workspace, stündlich berechnet: Kampagne gestartet oder gestoppt, Hochfahren, neues Land, neue Plattform, bezahlte Einstellung, Aktion, Launch, neuer Werbetreibender. Keine Credits. |
listCollectedAds | Lesen | read | Anzeigenerfassungen des Workspace (Meta, TikTok, Google, LinkedIn), bereits gelesen: die Liste oder, mit dem Namen einer Erfassung, ihre Aufschlüsselungen (Winkel, Angebote, Tonalitäten, Formate), ihr Rhythmus, ihre am längsten laufenden Anzeigen und ihre Anzeigen, gefiltert nach Bibliothek, Status, Winkel oder Wort. Keine Credits. |
Web und Register live erkunden#
Live-Lesezugriffe auf das Web und öffentliche Netzwerke. Sie verbrauchen Credits; im Workspace wird nichts gespeichert.
| Tool | Typ | Scopes | Rolle |
|---|---|---|---|
readPage | Live-Lesen | explore | Liest eine öffentliche Webseite: Titel, Haupttext (6.000 Zeichen), gefundene Feeds und 30 Links. |
searchWeb | Live-Lesen | explore | Durchsucht das öffentliche Web, um Kandidaten-URLs zu finden. |
browserRead | Live-Lesen | explore | Liest eine dynamische oder geschützte Seite mit erzwungenem Browser. Gleiche Form wie readPage. |
waybackHistory | Live-Lesen | explore | Wayback-Machine-Aufnahmen einer URL: erste Aufnahme und aktuelle Aufnahmen. |
registryLookup | Live-Lesen | explore | Sucht ein Unternehmen in einem öffentlichen Register: Sirene (Frankreich), EDGAR (USA), Companies House (Vereinigtes Königreich) oder OpenCorporates. |
socialCatalog | Live-Lesen | explore | Listet die Lese-Endpunkte der sozialen Netzwerke (höchstens 40), filterbar nach Plattform. |
socialCall | Live-Lesen | explore | Ruft einen Lese-Endpunkt eines sozialen Netzwerks auf und liefert bis zu 20 kompakte Items. |
previewSource | Live-Lesen | explore | Live-Stichprobe (5 bis 10 Items) einer Quelle, bevor Sie sie abonnieren. |
whoSaidItFirst | Live-Lesen | explore | Wer eine Information zuerst im Web veröffentlicht hat, Seite für Seite, und wann Ihre Quellen sie gesehen haben. Geht von einem Thema oder einem Item aus; als private Zeitleiste des Workspace gespeichert. |
Facebook#
Tools des Facebook-Agenten: Marketplace-Anzeigen und öffentliche Gruppen, live gelesen.
| Tool | Typ | Scopes | Rolle |
|---|---|---|---|
findMarketplaceLocation | Live-Lesen | explore | Wandelt den Namen einer Stadt oder Gegend in Marketplace-Koordinaten um. |
searchMarketplace | Live-Lesen | explore | Durchsucht öffentliche Marketplace-Anzeigen nach Stichwort rund um einen Ort (Stadt oder Koordinaten), über höchstens 3 Seiten. |
getMarketplaceListing | Live-Lesen | explore | Detail einer Anzeige: Beschreibung, Attribute, Fotos, Lieferung, genaues Datum, wenn Facebook es liefert. |
getMarketplaceListings | Live-Lesen | explore | Detail von 2 bis 6 Anzeigen auf einmal, als Vergleichstabelle. |
getFacebookGroup | Live-Lesen | explore | Öffentliches Profil einer Gruppe: Datenschutz, Größe, Aktivität, Kategorien, Regeln. |
getFacebookGroupPosts | Live-Lesen | explore | Beiträge einer öffentlichen Gruppe, in Seiten zu 3 (höchstens 6 Seiten). |
getFacebookPost | Live-Lesen | explore | Detail eines öffentlichen Beitrags oder Reels: Text, Autor, Datum, Reaktionen, Aufrufe. |
getFacebookPostComments | Live-Lesen | explore | Kommentare zu einem öffentlichen Beitrag, filterbar nach Stichwörtern (höchstens 3 Seiten). |
LinkedIn#
Tools des LinkedIn-Agenten: öffentliche Beiträge, Unternehmensseiten und Anzeigen, live gelesen. Kontaktdaten werden nie gelesen.
| Tool | Typ | Scopes | Rolle |
|---|---|---|---|
searchLinkedinPosts | Live-Lesen | explore | Durchsucht öffentliche Beiträge nach Stichwörtern in Echtzeit, neueste zuerst (ein partieller Lesevorgang wird im Ergebnis markiert), mit Titel und Rolle des Autors, wenn der Beitrag eine Stelle ausschreibt, und vom Code berechneten Signalen: Einstellung, Finanzierung, Launch, Expansion, Reorganisation, Verfügbarkeit, Abgang. |
probeLinkedinWatch | Live-Lesen | explore | Prüft 1 bis 3 Suchvarianten, bevor Sie eine LinkedIn-Beobachtung abonnieren, und liefert das Recherche-Ticket, das dem Abonnement beizufügen ist. |
getLinkedinPost | Live-Lesen | explore | Liest einen öffentlichen Beitrag oder Artikel: Text, Autor, Datum, Reaktionen, Kommentare mit ihren Signalen. |
getLinkedinPostTranscript | Live-Lesen | explore | Transkript des Videos eines öffentlichen Beitrags, nur berechnet, wenn es existiert. |
getLinkedinCompany | Live-Lesen | explore | Öffentliche Unternehmensseite: Beschreibung, Mitarbeiterzahl, Branche, Finanzierung, neueste Beiträge mit ihren Signalen. |
getLinkedinCompanyPosts | Live-Lesen | explore | Ältere Beiträge einer Unternehmensseite, mit einer Zusammenfassung der Signale (Einstellung, Finanzierung, Launches). |
searchLinkedinAds | Live-Lesen | explore | Durchsucht die Anzeigenbibliothek: Werbetreibender, Format, Daten, Impressionen. |
getLinkedinAd | Live-Lesen | explore | Detail einer Anzeige aus der Bibliothek: Targeting, Impressionen pro Land, Dauer. |
matchLinkedinPosts | Live-Lesen | explore | Bringt verfügbare Personen mit Gelegenheiten aus öffentlichen Beiträgen zusammen (zwei Suchen). |
getLinkedinProfile | Live-Lesen | explore | Begrenzter Lesevorgang eines öffentlichen /in/-Profils, nur ausgehend von einem öffentlichen Beitrag, der die Person nennt. Workspaces vorbehalten, die diese Option aktiviert haben. |
Upwork#
Tools des Upwork-Agenten: öffentliche Jobs lesen, bewerten und anhand der Wissensbasis des Workspace beantworten. An Upwork wird nichts gesendet.
| Tool | Typ | Scopes | Rolle |
|---|---|---|---|
searchUpworkJobs | Live-Lesen | explore | Liest eine Seite öffentlicher Ergebnisse (etwa zehn Jobs) und bewertet jeden Job anhand der Wissensbasis. Die Jobs werden der Pipeline des Workspace hinzugefügt. |
getUpworkJob | Live-Lesen | explore | Liest einen Job: Beschreibung, Skills, Budget, Aktivität, Kunde. Fügt der Pipeline einen datierten Snapshot hinzu. |
scoreUpworkJobs | Schreiben | write | Bewertet die Jobs der Pipeline nach einer Änderung der Wissensbasis erneut. Es wird keine Seite gelesen. |
getUpworkRadar | Live-Lesen | explore | Marktradar: Volumen pro Tag, Quartile von Satz und Budget, Skills, Wettbewerb, Länder der Kunden. |
listUpworkLeads | Lesen | read | Upwork-Pipeline: Anzahl pro Status, beste Jobs zuerst, Ergebnis jedes Jobs. |
updateUpworkLead | Schreiben | write | Ändert den Status eines Jobs der Pipeline (gesendet, Antwort, Gespräch, gewonnen, verloren, ignoriert) und behält eine Notiz. |
getUpworkKnowledge | Lesen | read | Upwork-Wissensbasis des Workspace: Leistungen, Werkzeuge, zu meidende Projekte, Mindestsätze, Fallstudien, Tonalität, Signatur. |
updateUpworkKnowledge | Schreiben | write | Aktualisiert die Wissensbasis. Von Ihnen gesendete Listen ersetzen die gespeicherten Listen. |
listUpworkTemplates | Lesen | read | Gespeicherte Angebotsvorlagen, mit ihren Slots und ihren Fragenregeln. |
upsertUpworkTemplate | Schreiben | write | Erstellt oder aktualisiert eine Angebotsvorlage. |
draftUpworkProposal | Schreiben | write, explore | Entwirft ein Angebot für einen Job anhand einer Vorlage. Den Text fügen Sie selbst auf Upwork ein. |
listUpworkCampaigns | Lesen | read | Gespeicherte Kampagnen: Suche, Mindestscore, Status, letzte Aktualisierung, Zustand der Quellen. |
saveUpworkCampaign | Schreiben | write | Erstellt oder aktualisiert eine Kampagne: Name, Suche, Mindestscore, Vorlage. |
simulateUpworkCampaign | Live-Lesen | explore | Simuliert eine Kampagne an echten Jobs, bevor Sie ihr folgen. Nichts wird gespeichert. |
followUpworkCampaign | Aktion | act | Bittet den Motor, einer gespeicherten Kampagne in ihrem Erfassungsrhythmus zu folgen. |
pauseUpworkCampaign | Aktion | act | Hält den Motor davon ab, einer Kampagne zu folgen. Bereits gesehene Jobs bleiben in der Pipeline. |
refreshUpworkCampaigns | Schreiben | write, explore | Aktualisiert die verfolgten Kampagnen: führt die vom Motor erfassten Jobs zusammen, liest die erste Seite erneut live und bewertet die neuen Jobs. |
checkUpworkOutcomes | Schreiben | write, explore | Liest die Seiten laufender Bewerbungen erneut, um ihr Ergebnis zu datieren: geschlossen, Gespräche begonnen, keine Antwort. |
syncUpworkReplies | Schreiben | write | Liest die Benachrichtigungs-E-Mails von Upwork in den verbundenen Postfächern des Schlüsselerstellers und setzt den Status von Pipeline-Jobs weiter. |
Im Workspace schreiben#
Tools des Piqline-Agenten, die Objekte des Workspace erstellen oder ändern. Sie verlangen den Scope write.
| Tool | Typ | Scopes | Rolle |
|---|---|---|---|
updateWorkspaceProfile | Schreiben | write | Speichert das Bedarfsprofil des Workspace: Ziele, Themen, Entitäten, Sprachen, Regionen, Niveau, Rhythmus. |
followEntity | Schreiben | write | Folgt einem Unternehmen, einer Marke oder einem öffentlichen Konto (nie einer Privatperson), um seine Items und Erwähnungen zu verknüpfen. |
unfollowEntity | Löschen | write | Beendet das Folgen einer Entität. Ihre bestehenden Verknüpfungen bleiben. |
saveBookmark | Schreiben | write | Speichert ein Lesezeichen im Tresor des Workspace. Eine http(s)-URL wird zum Lesen, Archivieren und Vektorisieren eingereiht. |
setWatchContract | Schreiben | write | Setzt einen Watch-Vertrag auf eine Quelle: Die Watch-Seite zeigt dann nur noch die passenden Items. Deterministisch, ohne Modell. |
removeWatchContract | Löschen | write | Entfernt den Watch-Vertrag einer Quelle: Alle Items erscheinen wieder. |
initReaderInterview | Schreiben | write | Speichert die zwei Antworten des Lese-Interviews (Wesentliches oder Detail, Hauptabsicht) im Leseprofil. |
applyBoardChange | Schreiben | write | Wendet bereits freigegebene Änderungen auf ein Board an. |
buildDashboard | Schreiben | write | Baut ein Board direkt, ohne den Widget-Picker. |
saveWorkspaceTable | Schreiben | write | Erstellt eine Workspace-Tabelle, gefüllt mit den nützlichen Spalten. |
writeFromWatch | Schreiben | write | Schreibt einen Text aus den Items der Beobachtungen des Workspace (Artikel, LinkedIn-Beitrag, X-Thread, Instagram-Bildunterschrift, Newsletter, Videoskript, Pressemitteilung, SEO-Artikel, E-Mail, Zusammenfassung), in neun Sprachen, jede Tatsache mit [n] auf ihre Quelle belegt; der Text kommt zu den Entwürfen. Verbraucht einige Credits. |
setTableFeed | Aktion | act, write | Erweckt eine Tabelle zum Leben: Sobald ein Item des Korpus zur Regel passt, wird es nach Bestätigung hinzugefügt. status=paused stoppt das Füllen. |
Auf Quellen und Regeln einwirken#
Aktions-Tools des Piqline-Agenten. Im Chat verlangt jedes eine Bestätigung. Über die API gilt ein direkter Aufruf mit dem Scope act als Bestätigung: Rufen Sie diese Tools erst auf, nachdem die betroffene Person zugestimmt hat.
| Tool | Typ | Scopes | Rolle |
|---|---|---|---|
subscribeSource | Aktion | act | Abonniert eine neue Quelle. Startet eine echte Erfassung (Lese-Jobs, Plattformkontingente). |
subscribeSources | Aktion | act | Abonniert mehrere Quellen in einem Aufruf und liefert ein Ergebnis pro Quelle. |
unsubscribeSource | Aktion | act | Beendet das Folgen einer Quelle. Bereits erfasste Items bleiben im Korpus. |
setHomeDashboard | Aktion | act | Setzt ein gespeichertes Board als Startseite des Workspace. |
upsertSignalRule | Aktion | act | Erstellt oder aktualisiert eine Persistenz-Signalregel: Sie löst aus, wenn ein Item länger als der Schwellenwert online bleibt. |
upsertQuestionRule | Aktion | act | Erstellt oder aktualisiert eine Dauerfrage: ein Satz in einfacher Sprache, den Jev an jedes neue Item der Quellen des Workspace stellt. Der Wahrscheinlichkeitsschwellenwert erzeugt das Signal. |
startInvestigation | Aktion | act | Reiht eine Edge-Recherche im Hintergrund für diesen Workspace ein (Owner oder Admin). |
startHunt | Aktion | act | Startet eine Suche: Personen finden, die nachprüfbare Kriterien erfüllen, jedes Kriterium durch eine datierte öffentliche Quelle belegt. Sensible Kriterien werden abgelehnt, es werden keine Kontaktdaten geliefert. Läuft im Hintergrund und verbraucht die Credits des Monats; Owner oder Admin. |
buildAdAudit | Schreiben | write | Rückwirkendes Audit der Kampagnen von 1 bis 6 bereits erfassten Werbetreibenden über N Monate: eine Workspace-Tabelle (Werbetreibender, Monat, neue Anzeigen, Stopps, Bibliotheken, Länder, gelesene Bedarfe, Hochfahren) und die Zahlen einer zitierten Zusammenfassung. Keine Credits. |
findCreatorSponsors | Aktion | act, write, explore | Wer YouTube-Creator in einer Nische bezahlt: Suche nach aktuellen Videos, aus jedem Video abgeleitete Sponsoren, eine Workspace-Tabelle „Sponsoren · Nische“. Verbraucht Credits; Bestätigung im Chat, Owner oder Admin. |
importAdHistory | Aktion | act, write, explore | Importiert den Google-Verlauf einer Werbetreibenden-Erfassung: bis zu 20 Seiten (etwa 800 Anzeigen seit 2021), um vergangene Kampagnen zu datieren. Verbraucht Credits; Bestätigung im Chat, Owner oder Admin. |
startAdCollection | Aktion | act, write, explore | Startet eine Anzeigenerfassung zu einem Werbetreibenden (Name oder Domain) oder einem Stichwort: liest Meta, TikTok, Google und LinkedIn, bringt jede Anzeige ins gleiche Format und liest dann Winkel, Angebot, Zielgruppe und Tonalität. Verbraucht Credits; Bestätigung im Chat, Owner oder Admin. |