Vai al contenuto

Guide

Tool

Chiama uno per uno i tool degli agenti, con i loro scope e i loro input.

Gli agenti Piqline lavorano con dei tool: leggere il corpus, cercare in diretta, scrivere, agire. L'API espone ciascuno di essi nella stessa forma. 92 tool sono richiamabili; il catalogo li elenca con i loro scope, e il riferimento descrive i parametri di ciascuno, con esempi di chiamata.

Elencare i tool#

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 accetta all (il valore predefinito), piqline, requete, facebook, linkedin, upwork oppure onboarding. Ogni tool dell'elenco contiene:

CampoSignificato
nameil nome del tool, come lo chiami
descriptionche cosa fa il tool, in inglese, come lo legge l'agente
agentsgli agenti che hanno il tool
requiresgli scope richiesti
callabletrue se la tua chiave può chiamarlo
missing_scopesgli scope che la chiave non ha
confirmation_in_chattrue se la chat chiede conferma prima di eseguire il tool
read_onlytrue se il tool non modifica nulla
input_schemaJSON Schema dell'input

I tool che la tua chiave non può chiamare restano nell'elenco, con callable: false e missing_scopes. GET/api/v1/tools/{nom} restituisce la stessa voce per un singolo tool, senza confirmation_in_chat né read_only.

Chiamare un tool#

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

Il corpo JSON è l'input del tool, come lo descrive input_schema. Un tool senza input accetta un corpo vuoto.

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

La risposta contiene il nome del tool e il suo output, lo stesso output che legge l'agente:

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 è la data di visualizzazione dell'elemento. getItem restituisce anche detectedAt (visto per la prima volta da Piqline), lastSeenAt (visto per l'ultima volta) e publishedAt.

Un errore torna come application/problem+json: vedi Errori.

Chi può chiamare che cosa#

  • Il ruolo del creatore limita la chiave. Un tool che quel ruolo non apre risponde 403 forbidden. I tool di scrittura, i tool di azione e l'agente onboarding sono riservati a owner e admin.
  • Le card della chat non esistono nell'API. askUser, proposeSources, proposeBoard e simili vengono mostrati a una persona e non eseguono nulla: rispondono 404 not_found. Per ottenere quel dialogo, esegui un agente.
  • I tool di azione non aspettano conferma. La chat la chiede. Una chiamata diretta con lo scope act viene eseguita subito.
  • Le letture in diretta consumano crediti. I tool dello scope explore prelevano crediti dal limite mensile del workspace.

Leggere il corpus e il workspace#

Tool dell'agente Piqline. Leggono ciò che il workspace ha già raccolto: nessun credito consumato, nulla viene scritto.

ToolTipoScopeRuolo
getCoverageStatsLetturareadVolumi e stato della raccolta: totali, suddivisione per piattaforma e per tipo, serie di acquisizione sulla finestra di analisi (1h, 24h, 7d o 30d).
listSourcesLetturareadFonti seguite dal workspace, con numero di elementi, stato e ultima lettura.
searchItemsLetturareadCerca elementi (post, video, articoli, inserzioni, offerte di lavoro) con filtri: testo, piattaforma, tipo, fonte. Senza filtro, restituisce i più recenti (al massimo 40).
getItemLetturareadDettaglio di un elemento: testo, trascrizione, OCR, argomenti rilevati, elementi vicini per significato e date di osservazione.
searchPassagesLetturareadRicerca per significato nei documenti lunghi (PDF letti dal Motor): i passaggi più vicini a una domanda, con l'elemento, la pagina e il titolo della sezione.
citeItemLetturareadVerifica che un passaggio compaia parola per parola in un elemento e restituisce un numero di citazione; altrimenti il passaggio più vicino. Base della modalità Citazioni della chat.
drawDiagramLetturareadDisegna la risposta come diagramma SVG (timeline, matrice, flusso, albero…): colori per ruolo del tema, SVG ripulito prima della visualizzazione. Base della modalità Diagramma della chat.
createCanvasLetturareadCompila un canvas (un file TSX che importa solo l'SDK piqline/canvas) e restituisce il codice pronto da visualizzare, oppure l'errore da correggere. Base delle modalità Canvas e Report della chat.
getTopicsLetturareadArgomenti rilevati con la loro quota di voce e le storie (lo stesso soggetto visto in più fonti).
getSignalsLetturareadSegnali aperti, attivati dalle regole di persistenza del workspace, con il loro anticipo e il loro stato.
listWorkspaceTablesLetturareadTabelle già create nel workspace: nome, commento, numero di colonne e di righe, e se la tabella si popola da sola.
getWorkspaceTableLetturareadUna tabella del workspace in JSON: schema, colonne e righe. Serve da base o da feed per un sito, un'app o un agente (scope read).
listBookmarksLetturareadSegnalibri e cartelle del vault del workspace: titolo, tipo, cartella, stato, ammissione. Filtro facoltativo per parola, stato o tipo.
listEntitiesLetturareadEntità seguite (aziende, marchi, account pubblici) ed elementi collegati nel periodo.
listWatchContractsLetturareadContratti di monitoraggio impostati sulle fonti: intento, termini mantenuti ed esclusi, evento.
checkInvestigationLetturareadStato dell'ultima indagine Edge, o di una indagine specifica: in attesa, in corso, conclusa con i suoi candidati, oppure fallita.
checkHuntLetturareadStato dell'ultima ricerca, o di una ricerca specifica: fase, persone trovate con il verdetto del codice e il tuo, e per ogni criterio il suo stato e la sua prova pubblica datata (URL, data, estratto). Mai recapiti.
planSourcePackLetturareadPropone un insieme coerente di fonti da seguire per un obiettivo. Non crea nulla.
listWidgetsLetturareadWidget che possono andare su una board di questo workspace, ordinati per la persona, con le loro motivazioni.
getAdvertiserCampaignsLetturareadScheda delle inserzioni di un inserzionista dalle raccolte del workspace: inserzioni, quelle attive, date, librerie, paesi, esigenze lette, nuove inserzioni al mese e aumenti di ritmo, ultime inserzioni, segnali. Mai una persona. Nessun credito.
listAdSignalsLetturareadSegnali pubblicitari del workspace, calcolati ogni ora: campagna avviata o interrotta, aumento di ritmo, nuovo paese, nuova piattaforma, assunzione a pagamento, promozione, lancio, nuovo inserzionista. Nessun credito.
listCollectedAdsLetturareadRaccolte di inserzioni del workspace (Meta, TikTok, Google, LinkedIn), già lette: l'elenco oppure, con il nome di una raccolta, le sue suddivisioni (angoli, offerte, toni, formati), il suo ritmo, le sue inserzioni più longeve e le sue inserzioni filtrate per libreria, stato, angolo o parola. Nessun credito.

Esplorare il web e i registri in diretta#

Letture in diretta sul web e sulle reti pubbliche. Consumano crediti; nulla viene salvato nel workspace.

ToolTipoScopeRuolo
readPageLettura in direttaexploreLegge una pagina web pubblica: titolo, testo principale (6.000 caratteri), feed individuati e 30 link.
searchWebLettura in direttaexploreCerca nel web pubblico per trovare URL candidati.
browserReadLettura in direttaexploreLegge una pagina dinamica o protetta con un browser forzato. Stessa forma di readPage.
waybackHistoryLettura in direttaexploreCatture della Wayback Machine di un URL: prima cattura e catture recenti.
registryLookupLettura in direttaexploreCerca un'azienda in un registro pubblico: Sirene (Francia), EDGAR (Stati Uniti), Companies House (Regno Unito) oppure OpenCorporates.
socialCatalogLettura in direttaexploreElenca gli endpoint di lettura dei social network (al massimo 40), filtrabili per piattaforma.
socialCallLettura in direttaexploreChiama un endpoint di lettura di un social network e restituisce fino a 20 elementi compatti.
previewSourceLettura in direttaexploreCampione in diretta (da 5 a 10 elementi) di una fonte, prima di iscriversi.
whoSaidItFirstLettura in direttaexploreChi ha pubblicato per primo un'informazione sul web, pagina per pagina, e quando le tue fonti l'hanno vista. Parte da un argomento o da un elemento; conservato come timeline privata del workspace.

Facebook#

Tool dell'agente Facebook: annunci di Marketplace e gruppi pubblici, letti in diretta.

ToolTipoScopeRuolo
findMarketplaceLocationLettura in direttaexploreTrasforma il nome di una città o di un'area in coordinate di Marketplace.
searchMarketplaceLettura in direttaexploreCerca gli annunci pubblici di Marketplace per parola chiave attorno a un luogo (città o coordinate), su 3 pagine al massimo.
getMarketplaceListingLettura in direttaexploreDettaglio di un annuncio: descrizione, attributi, foto, consegna, data esatta quando Facebook la fornisce.
getMarketplaceListingsLettura in direttaexploreDettaglio di 2-6 annunci insieme, come tabella di confronto.
getFacebookGroupLettura in direttaexploreProfilo pubblico di un gruppo: privacy, dimensione, attività, categorie, regole.
getFacebookGroupPostsLettura in direttaexplorePost di un gruppo pubblico, in pagine da 3 (al massimo 6 pagine).
getFacebookPostLettura in direttaexploreDettaglio di un post o reel pubblico: testo, autore, data, reazioni, visualizzazioni.
getFacebookPostCommentsLettura in direttaexploreCommenti a un post pubblico, filtrabili per parole chiave (al massimo 3 pagine).

LinkedIn#

Tool dell'agente LinkedIn: post pubblici, pagine aziendali e inserzioni, letti in diretta. I recapiti non vengono mai letti.

ToolTipoScopeRuolo
searchLinkedinPostsLettura in direttaexploreCerca post pubblici per parole chiave, in tempo reale, dal più recente (una lettura parziale è segnalata nel risultato), con il titolo e il ruolo dell'autore quando il post riguarda un'assunzione, e segnali calcolati dal codice: assunzione, raccolta fondi, lancio, espansione, riorganizzazione, disponibilità, partenza.
probeLinkedinWatchLettura in direttaexploreSonda da 1 a 3 varianti di query prima di iscriversi a un monitoraggio LinkedIn, e restituisce il ticket di indagine da allegare all'iscrizione.
getLinkedinPostLettura in direttaexploreLegge un post o un articolo pubblico: testo, autore, data, reazioni, commenti con i loro segnali.
getLinkedinPostTranscriptLettura in direttaexploreTrascrizione del video di un post pubblico, fatturata solo se esiste.
getLinkedinCompanyLettura in direttaexplorePagina aziendale pubblica: descrizione, organico, settore, finanziamenti, ultimi post con i loro segnali.
getLinkedinCompanyPostsLettura in direttaexplorePost meno recenti di una pagina aziendale, con un riepilogo dei segnali (assunzioni, finanziamenti, lanci).
searchLinkedinAdsLettura in direttaexploreCerca nella libreria delle inserzioni: inserzionista, formato, date, impression.
getLinkedinAdLettura in direttaexploreDettaglio di un'inserzione della libreria: targeting, impression per paese, durata.
matchLinkedinPostsLettura in direttaexploreAbbina persone disponibili a opportunità a partire da post pubblici (due ricerche).
getLinkedinProfileLettura in direttaexploreLettura limitata di un profilo pubblico /in/, solo a partire da un post pubblico che nomina la persona. Riservato ai workspace che hanno attivato questa opzione.

Upwork#

Tool dell'agente Upwork: offerte pubbliche lette, valutate e riscontrate a partire dalla knowledge base del workspace. Nulla viene inviato a Upwork.

ToolTipoScopeRuolo
searchUpworkJobsLettura in direttaexploreLegge una pagina di risultati pubblici (una decina di offerte) e valuta ciascuna offerta rispetto alla knowledge base. Le offerte vengono aggiunte alla pipeline del workspace.
getUpworkJobLettura in direttaexploreLegge un'offerta: descrizione, competenze, budget, attività, cliente. Aggiunge alla pipeline un'istantanea datata.
scoreUpworkJobsScritturawriteRivaluta le offerte della pipeline dopo una modifica della knowledge base. Nessuna pagina viene letta.
getUpworkRadarLettura in direttaexploreRadar di mercato: volume al giorno, quartili di tariffa e di budget, competenze, concorrenza, paesi dei clienti.
listUpworkLeadsLetturareadPipeline Upwork: conteggio per stato, prima le migliori offerte, esito di ciascuna.
updateUpworkLeadScritturawriteModifica lo stato di un'offerta della pipeline (inviata, risposta, colloquio, vinta, persa, ignorata) e conserva una nota.
getUpworkKnowledgeLetturareadKnowledge base Upwork del workspace: servizi, strumenti, progetti da evitare, tariffe minime, casi di studio, tono, firma.
updateUpworkKnowledgeScritturawriteAggiorna la knowledge base. Gli elenchi che invii sostituiscono quelli memorizzati.
listUpworkTemplatesLetturareadModelli di proposta salvati, con i loro slot e le loro regole per le domande.
upsertUpworkTemplateScritturawriteCrea o aggiorna un modello di proposta.
draftUpworkProposalScritturawrite, exploreRedige una bozza di proposta per un'offerta a partire da un modello. Incolli tu stesso il testo su Upwork.
listUpworkCampaignsLetturareadCampagne salvate: ricerca, punteggio minimo, stato, ultimo aggiornamento, stato delle fonti.
saveUpworkCampaignScritturawriteCrea o aggiorna una campagna: nome, ricerca, punteggio minimo, modello.
simulateUpworkCampaignLettura in direttaexploreSimula una campagna su offerte reali prima di seguirla. Nulla viene salvato.
followUpworkCampaignAzioneactChiede al Motor di seguire una campagna salvata, al suo ritmo di raccolta.
pauseUpworkCampaignAzioneactImpedisce al Motor di seguire una campagna. Le offerte già viste restano nella pipeline.
refreshUpworkCampaignsScritturawrite, exploreAggiorna le campagne seguite: unisce le offerte raccolte dal Motor, rilegge in diretta la prima pagina, valuta le nuove offerte.
checkUpworkOutcomesScritturawrite, exploreRilegge le pagine delle candidature in corso per datare il loro esito: chiusa, colloqui avviati, nessuna risposta.
syncUpworkRepliesScritturawriteLegge le e-mail di notifica di Upwork nelle caselle collegate del creatore della chiave e fa avanzare lo stato delle offerte della pipeline.

Scrivere nel workspace#

Tool dell'agente Piqline che creano o modificano oggetti del workspace. Richiedono lo scope write.

ToolTipoScopeRuolo
updateWorkspaceProfileScritturawriteSalva il profilo di esigenza del workspace: obiettivi, argomenti, entità, lingue, regioni, livello, ritmo.
followEntityScritturawriteSegue un'azienda, un marchio o un account pubblico (mai una persona privata) per collegare i suoi elementi e le sue menzioni.
unfollowEntityEliminazionewriteSmette di seguire un'entità. I suoi collegamenti esistenti restano.
saveBookmarkScritturawriteSalva un segnalibro nel vault del workspace. Un URL http(s) viene messo in coda per la lettura, l'archiviazione e la vettorizzazione.
setWatchContractScritturawriteImposta un contratto di monitoraggio su una fonte: la pagina di monitoraggio mostra poi solo gli elementi corrispondenti. Deterministico, senza modello.
removeWatchContractEliminazionewriteRimuove il contratto di monitoraggio di una fonte: tutti gli elementi tornano visibili.
initReaderInterviewScritturawriteSalva le due risposte dell'intervista di lettura (essenziale o dettaglio, intento principale) nel profilo di lettura.
applyBoardChangeScritturawriteApplica a una board modifiche già approvate.
buildDashboardScritturawriteCostruisce direttamente una board, senza passare dalla selezione dei widget.
saveWorkspaceTableScritturawriteCrea una tabella del workspace, popolata con le colonne utili.
writeFromWatchScritturawriteScrive un testo a partire dagli elementi dei monitoraggi del workspace (articolo, post LinkedIn, thread X, didascalia Instagram, newsletter, script video, comunicato stampa, articolo SEO, e-mail, riepilogo), in nove lingue, con ogni fatto citato [n] rispetto alla sua fonte; il testo entra nelle bozze. Consuma alcuni crediti.
setTableFeedAzioneact, writeDà vita a una tabella: non appena un elemento del corpus corrisponde alla regola, viene aggiunto, dopo conferma. status=paused interrompe il popolamento.

Agire su fonti e regole#

Tool di azione dell'agente Piqline. Nella chat, ciascuno chiede conferma. Tramite l'API, una chiamata diretta con lo scope act vale come conferma: chiama questi tool solo dopo che la persona interessata ha dato il suo consenso.

ToolTipoScopeRuolo
subscribeSourceAzioneactSi iscrive a una nuova fonte. Avvia una vera raccolta (job di lettura, quote delle piattaforme).
subscribeSourcesAzioneactSi iscrive a più fonti in una sola chiamata e restituisce un risultato per fonte.
unsubscribeSourceAzioneactSmette di seguire una fonte. Gli elementi già raccolti restano nel corpus.
setHomeDashboardAzioneactImposta una board salvata come home del workspace.
upsertSignalRuleAzioneactCrea o aggiorna una regola di segnale di persistenza: scatta quando un elemento resta online più a lungo della soglia.
upsertQuestionRuleAzioneactCrea o aggiorna una domanda permanente: una frase in linguaggio naturale che Jev pone a ogni nuovo elemento delle fonti del workspace. La soglia di probabilità genera il segnale.
startInvestigationAzioneactMette in coda un'indagine Edge in background per questo workspace (owner o admin).
startHuntAzioneactAvvia una ricerca: trova persone che soddisfano criteri verificabili, con ogni criterio provato da una fonte pubblica datata. I criteri sensibili sono rifiutati, non viene restituito alcun recapito. Viene eseguita in background e consuma i crediti del mese; owner o admin.
buildAdAuditScritturawriteAudit retroattivo delle campagne di 1-6 inserzionisti già raccolti, su N mesi: una tabella del workspace (inserzionista, mese, nuove inserzioni, interruzioni, librerie, paesi, esigenze lette, aumento di ritmo) e le cifre di un riepilogo citato. Nessun credito.
findCreatorSponsorsAzioneact, write, exploreChi paga i creator YouTube in una nicchia: ricerca di video recenti, sponsor dedotti da ciascun video, una tabella del workspace «Sponsor · nicchia». Consuma crediti; conferma nella chat, owner o admin.
importAdHistoryAzioneact, write, exploreImporta la cronologia Google di una raccolta di un inserzionista: fino a 20 pagine (circa 800 inserzioni dal 2021) per datare le campagne passate. Consuma crediti; conferma nella chat, owner o admin.
startAdCollectionAzioneact, write, exploreAvvia una raccolta di inserzioni su un inserzionista (nome o dominio) o su una parola chiave: legge Meta, TikTok, Google e LinkedIn, porta ogni inserzione nello stesso formato, poi legge l'angolo, l'offerta, il pubblico e il tono. Consuma crediti; conferma nella chat, owner o admin.

Una domanda sull'API, o un errore in questa pagina? Scrivici.