Guías
Herramientas
Llama una a una a las herramientas de los agentes, con sus scopes y entradas.
Los agentes de Piqline trabajan con herramientas: leer el corpus, buscar en directo, escribir, actuar. La API expone cada una con la misma forma. Hay 92 herramientas invocables; el catálogo las lista con sus scopes y la referencia describe los parámetros de cada una, con ejemplos de llamada.
Listar las herramientas#
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 acepta all (el valor por defecto), piqline, requete, facebook, linkedin, upwork u onboarding. Cada herramienta de la lista incluye:
| Campo | Significado |
|---|---|
name | el nombre de la herramienta, tal como se llama |
description | qué hace la herramienta, en inglés, tal como la lee el agente |
agents | los agentes que tienen la herramienta |
requires | los scopes requeridos |
callable | true si tu clave puede llamarla |
missing_scopes | scopes que la clave no tiene |
confirmation_in_chat | true si el chat pide confirmación antes de ejecutar la herramienta |
read_only | true si la herramienta no cambia nada |
input_schema | JSON Schema de la entrada |
Las herramientas que tu clave no puede llamar siguen en la lista, con callable: false y missing_scopes. GET/api/v1/tools/{nom} devuelve la misma entrada para una sola herramienta, sin confirmation_in_chat ni read_only.
Llamar a una herramienta#
POST https://piqline.com/api/v1/tools/{nom}
Content-Type: application/jsonEl cuerpo JSON es la entrada de la herramienta, tal como la describe input_schema. Una herramienta sin entrada acepta un cuerpo vacío.
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()La respuesta incluye el nombre de la herramienta y su salida, la misma que lee el agente:
{
"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 es la fecha de visualización del elemento. getItem devuelve además detectedAt (primera vez que Piqline lo vio), lastSeenAt (última vez que lo vio) y publishedAt.
Un error llega como application/problem+json: consulta Errores.
Quién puede llamar a qué#
- El rol del creador limita la clave. Una herramienta que ese rol no abre responde
403 forbidden. Las herramientas de escritura, las de acción y el agenteonboardingestán reservadas a propietarios y administradores. - Las tarjetas del chat no existen en la API.
askUser,proposeSources,proposeBoardy similares se muestran a una persona y no ejecutan nada: responden404 not_found. Para obtener ese diálogo, ejecuta un agente. - Las herramientas de acción no esperan confirmación. El chat la pide. Una llamada directa con el scope
actse ejecuta de inmediato. - Las lecturas en directo consumen créditos. Las herramientas del scope
exploredescuentan créditos del tope mensual del workspace.
Catálogo#
Leer el corpus y el workspace#
Herramientas del agente Piqline. Leen lo que el workspace ya ha recogido: no consumen créditos y no escriben nada.
| Herramienta | Tipo | Scopes | Función |
|---|---|---|---|
getCoverageStats | Lectura | read | Volúmenes y estado de la recogida: totales, desglose por plataforma y por tipo, series de ingesta en la ventana de análisis (1h, 24h, 7d o 30d). |
listSources | Lectura | read | Fuentes que sigue el workspace, con número de elementos, estado y última lectura. |
searchItems | Lectura | read | Busca elementos (publicaciones, vídeos, artículos, anuncios, ofertas) con filtros: texto, plataforma, tipo, fuente. Sin filtro, devuelve los más recientes (40 como máximo). |
getItem | Lectura | read | Detalle de un elemento: texto, transcripción, OCR, temas detectados, elementos de sentido cercano y sus fechas de observación. |
searchPassages | Lectura | read | Búsqueda por sentido en documentos largos (PDF leídos por el Motor): los pasajes más cercanos a una pregunta, con el elemento, la página y el título de la sección. |
citeItem | Lectura | read | Comprueba que un pasaje aparece palabra por palabra en un elemento y devuelve un número de cita; si no, el pasaje más cercano. Base del modo Citas del chat. |
drawDiagram | Lectura | read | Dibuja la respuesta como un diagrama SVG (línea de tiempo, matriz, flujo, árbol…): colores por rol del tema, SVG saneado antes de mostrarse. Base del modo Diagrama del chat. |
createCanvas | Lectura | read | Compila un canvas (un archivo TSX que solo importa el SDK piqline/canvas) y devuelve código listo para mostrar, o el error que hay que corregir. Base de los modos Canvas e Informe del chat. |
getTopics | Lectura | read | Temas detectados con su cuota de voz, e historias (el mismo asunto visto en varias fuentes). |
getSignals | Lectura | read | Señales abiertas, activadas por las reglas de persistencia del workspace, con su antelación y su estado. |
listWorkspaceTables | Lectura | read | Tablas ya creadas en el workspace: nombre, comentario, número de columnas y filas, y si la tabla se rellena sola. |
getWorkspaceTable | Lectura | read | Una tabla del workspace en JSON: esquema, columnas y filas. Sirve de base o de fuente para un sitio, una aplicación o un agente (scope read). |
listBookmarks | Lectura | read | Marcadores y carpetas de la bóveda del workspace: título, tipo, carpeta, estado, admisión. Filtro opcional por palabra, estado o tipo. |
listEntities | Lectura | read | Entidades seguidas (empresas, marcas, cuentas públicas) y elementos vinculados en el período. |
listWatchContracts | Lectura | read | Contratos de vigilancia definidos sobre las fuentes: intención, términos conservados y excluidos, evento. |
checkInvestigation | Lectura | read | Estado de la última investigación de Edge, o de una concreta: pendiente, en curso, terminada con sus candidatos, o fallida. |
checkHunt | Lectura | read | Estado de la última búsqueda, o de una concreta: etapa, personas encontradas con el veredicto del código y el tuyo, y, para cada criterio, su estado y su prueba pública fechada (URL, fecha, extracto). Nunca datos de contacto. |
planSourcePack | Lectura | read | Propone un conjunto coherente de fuentes que seguir para un objetivo. No crea nada. |
listWidgets | Lectura | read | Widgets que pueden ir en un tablero de este workspace, ordenados para la persona, con sus motivos. |
getAdvertiserCampaigns | Lectura | read | Ficha publicitaria de un anunciante a partir de las colecciones del workspace: anuncios, los activos, fechas, bibliotecas, países, necesidades leídas, anuncios nuevos por mes y aumentos de ritmo, últimos anuncios, señales. Nunca una persona. Sin créditos. |
listAdSignals | Lectura | read | Señales publicitarias del workspace, calculadas cada hora: campaña iniciada o detenida, aumento de ritmo, nuevo país, nueva plataforma, contratación pagada, promoción, lanzamiento, nuevo anunciante. Sin créditos. |
listCollectedAds | Lectura | read | Colecciones de anuncios del workspace (Meta, TikTok, Google, LinkedIn), ya leídas: la lista o, con el nombre de una colección, sus desgloses (ángulos, ofertas, tonos, formatos), su ritmo, sus anuncios más longevos y sus anuncios filtrados por biblioteca, estado, ángulo o palabra. Sin créditos. |
Explorar la web y los registros en directo#
Lecturas en directo de la web y de las redes públicas. Consumen créditos; no se guarda nada en el workspace.
| Herramienta | Tipo | Scopes | Función |
|---|---|---|---|
readPage | Lectura en directo | explore | Lee una página web pública: título, texto principal (6000 caracteres), feeds descubiertos y 30 enlaces. |
searchWeb | Lectura en directo | explore | Busca en la web pública para encontrar URL candidatas. |
browserRead | Lectura en directo | explore | Lee una página dinámica o protegida con un navegador forzado. Misma forma que readPage. |
waybackHistory | Lectura en directo | explore | Capturas de Wayback Machine de una URL: primera captura y capturas recientes. |
registryLookup | Lectura en directo | explore | Busca una empresa en un registro público: Sirene (Francia), EDGAR (Estados Unidos), Companies House (Reino Unido) u OpenCorporates. |
socialCatalog | Lectura en directo | explore | Lista los endpoints de lectura de redes sociales (40 como máximo), filtrables por plataforma. |
socialCall | Lectura en directo | explore | Llama a un endpoint de lectura de una red social y devuelve hasta 20 elementos compactos. |
previewSource | Lectura en directo | explore | Muestra en directo (5 a 10 elementos) de una fuente, antes de suscribirse a ella. |
whoSaidItFirst | Lectura en directo | explore | Quién publicó primero una información en la web, página por página, y cuándo la vieron tus fuentes. Parte de un tema o de un elemento; se conserva como línea de tiempo privada del workspace. |
Facebook#
Herramientas del agente de Facebook: anuncios de Marketplace y grupos públicos, leídos en directo.
| Herramienta | Tipo | Scopes | Función |
|---|---|---|---|
findMarketplaceLocation | Lectura en directo | explore | Convierte el nombre de una ciudad o zona en coordenadas de Marketplace. |
searchMarketplace | Lectura en directo | explore | Busca anuncios públicos de Marketplace por palabra clave en torno a un lugar (ciudad o coordenadas), en 3 páginas como máximo. |
getMarketplaceListing | Lectura en directo | explore | Detalle de un anuncio: descripción, atributos, fotos, envío, fecha exacta cuando Facebook la proporciona. |
getMarketplaceListings | Lectura en directo | explore | Detalle de 2 a 6 anuncios a la vez, como tabla comparativa. |
getFacebookGroup | Lectura en directo | explore | Perfil público de un grupo: privacidad, tamaño, actividad, categorías, reglas. |
getFacebookGroupPosts | Lectura en directo | explore | Publicaciones de un grupo público, en páginas de 3 (6 páginas como máximo). |
getFacebookPost | Lectura en directo | explore | Detalle de una publicación o reel público: texto, autor, fecha, reacciones, visualizaciones. |
getFacebookPostComments | Lectura en directo | explore | Comentarios de una publicación pública, filtrables por palabras clave (3 páginas como máximo). |
LinkedIn#
Herramientas del agente de LinkedIn: publicaciones públicas, páginas de empresa y anuncios, leídos en directo. Los datos de contacto nunca se leen.
| Herramienta | Tipo | Scopes | Función |
|---|---|---|---|
searchLinkedinPosts | Lectura en directo | explore | Busca publicaciones públicas por palabras clave, en tiempo real, de más reciente a más antigua (una lectura parcial se señala en el resultado), con el cargo y el rol del autor cuando la publicación es una oferta de empleo, y señales calculadas por código: contratación, captación de fondos, lanzamiento, expansión, reorganización, disponibilidad, salida. |
probeLinkedinWatch | Lectura en directo | explore | Prueba de 1 a 3 variantes de consulta antes de suscribirse a una vigilancia de LinkedIn, y devuelve el ticket de investigación que se adjunta a la suscripción. |
getLinkedinPost | Lectura en directo | explore | Lee una publicación o artículo público: texto, autor, fecha, reacciones, comentarios con sus señales. |
getLinkedinPostTranscript | Lectura en directo | explore | Transcripción del vídeo de una publicación pública, facturada solo si existe. |
getLinkedinCompany | Lectura en directo | explore | Página pública de empresa: descripción, plantilla, sector, financiación, últimas publicaciones con sus señales. |
getLinkedinCompanyPosts | Lectura en directo | explore | Publicaciones anteriores de una página de empresa, con un resumen de las señales (contratación, financiación, lanzamientos). |
searchLinkedinAds | Lectura en directo | explore | Busca en la biblioteca de anuncios: anunciante, formato, fechas, impresiones. |
getLinkedinAd | Lectura en directo | explore | Detalle de un anuncio de la biblioteca: segmentación, impresiones por país, duración. |
matchLinkedinPosts | Lectura en directo | explore | Empareja personas disponibles con oportunidades a partir de publicaciones públicas (dos búsquedas). |
getLinkedinProfile | Lectura en directo | explore | Lectura acotada de un perfil público /in/, solo a partir de una publicación pública que nombra a la persona. Reservada a los workspaces que han activado esta opción. |
Upwork#
Herramientas del agente de Upwork: ofertas públicas leídas, puntuadas y respondidas a partir de la base de conocimiento del workspace. No se envía nada a Upwork.
| Herramienta | Tipo | Scopes | Función |
|---|---|---|---|
searchUpworkJobs | Lectura en directo | explore | Lee una página de resultados públicos (unas diez ofertas) y puntúa cada oferta frente a la base de conocimiento. Las ofertas se añaden al pipeline del workspace. |
getUpworkJob | Lectura en directo | explore | Lee una oferta: descripción, habilidades, presupuesto, actividad, cliente. Añade una instantánea fechada al pipeline. |
scoreUpworkJobs | Escritura | write | Vuelve a puntuar las ofertas del pipeline tras un cambio en la base de conocimiento. No se lee ninguna página. |
getUpworkRadar | Lectura en directo | explore | Radar de mercado: volumen por día, cuartiles de tarifa y presupuesto, habilidades, competencia, países de los clientes. |
listUpworkLeads | Lectura | read | Pipeline de Upwork: recuento por estado, mejores ofertas primero, resultado de cada una. |
updateUpworkLead | Escritura | write | Cambia el estado de una oferta del pipeline (enviada, respuesta, entrevista, ganada, perdida, ignorada) y guarda una nota. |
getUpworkKnowledge | Lectura | read | Base de conocimiento de Upwork del workspace: servicios, herramientas, proyectos que evitar, tarifas mínimas, casos de estudio, tono, firma. |
updateUpworkKnowledge | Escritura | write | Actualiza la base de conocimiento. Las listas que envías sustituyen a las listas almacenadas. |
listUpworkTemplates | Lectura | read | Plantillas de propuesta guardadas, con sus campos y sus reglas de preguntas. |
upsertUpworkTemplate | Escritura | write | Crea o actualiza una plantilla de propuesta. |
draftUpworkProposal | Escritura | write, explore | Redacta una propuesta para una oferta a partir de una plantilla. El texto lo pegas tú mismo en Upwork. |
listUpworkCampaigns | Lectura | read | Campañas guardadas: búsqueda, puntuación mínima, estado, última actualización, estado de las fuentes. |
saveUpworkCampaign | Escritura | write | Crea o actualiza una campaña: nombre, búsqueda, puntuación mínima, plantilla. |
simulateUpworkCampaign | Lectura en directo | explore | Simula una campaña con ofertas reales antes de seguirla. No se guarda nada. |
followUpworkCampaign | Acción | act | Pide al Motor que siga una campaña guardada, a su ritmo de recogida. |
pauseUpworkCampaign | Acción | act | Hace que el Motor deje de seguir una campaña. Las ofertas ya vistas permanecen en el pipeline. |
refreshUpworkCampaigns | Escritura | write, explore | Actualiza las campañas seguidas: fusiona las ofertas recogidas por el Motor, vuelve a leer la primera página en directo y puntúa las ofertas nuevas. |
checkUpworkOutcomes | Escritura | write, explore | Vuelve a leer las páginas de las candidaturas en curso para fechar su resultado: cerrada, entrevistas iniciadas, sin respuesta. |
syncUpworkReplies | Escritura | write | Lee los correos de notificación de Upwork en las bandejas conectadas del creador de la clave y hace avanzar el estado de las ofertas del pipeline. |
Escribir en el workspace#
Herramientas del agente Piqline que crean o modifican objetos del workspace. Requieren el scope write.
| Herramienta | Tipo | Scopes | Función |
|---|---|---|---|
updateWorkspaceProfile | Escritura | write | Guarda el perfil de necesidades del workspace: objetivos, temas, entidades, idiomas, regiones, nivel, ritmo. |
followEntity | Escritura | write | Sigue una empresa, una marca o una cuenta pública (nunca una persona privada) para vincular sus elementos y menciones. |
unfollowEntity | Eliminación | write | Deja de seguir una entidad. Sus vínculos existentes permanecen. |
saveBookmark | Escritura | write | Guarda un marcador en la bóveda del workspace. Una URL http(s) se pone en cola para lectura, archivado y vectorización. |
setWatchContract | Escritura | write | Define un contrato de vigilancia sobre una fuente: la página de vigilancia solo muestra entonces los elementos que coinciden. Determinista, sin modelo. |
removeWatchContract | Eliminación | write | Elimina el contrato de vigilancia de una fuente: se vuelven a mostrar todos los elementos. |
initReaderInterview | Escritura | write | Guarda las dos respuestas de la entrevista de lectura (lo esencial o el detalle, intención principal) en el perfil de lectura. |
applyBoardChange | Escritura | write | Aplica a un tablero cambios que ya fueron aprobados. |
buildDashboard | Escritura | write | Construye un tablero directamente, sin pasar por el selector de widgets. |
saveWorkspaceTable | Escritura | write | Crea una tabla del workspace, rellenada con las columnas útiles. |
writeFromWatch | Escritura | write | Redacta un texto a partir de los elementos de las vigilancias del workspace (artículo, publicación de LinkedIn, hilo de X, pie de foto de Instagram, boletín, guion de vídeo, nota de prensa, artículo SEO, correo, resumen), en nueve idiomas, con cada dato citado [n] a su fuente; el texto se une a los borradores. Consume unos pocos créditos. |
setTableFeed | Acción | act, write | Da vida a una tabla: en cuanto un elemento del corpus cumple la regla, se añade, previa confirmación. status=paused detiene el rellenado. |
Actuar sobre fuentes y reglas#
Herramientas de acción del agente Piqline. En el chat, cada una pide confirmación. Por la API, una llamada directa con el scope act cuenta como confirmación: llama a estas herramientas solo después de que la persona afectada lo haya aceptado.
| Herramienta | Tipo | Scopes | Función |
|---|---|---|---|
subscribeSource | Acción | act | Se suscribe a una fuente nueva. Inicia una recogida real (trabajos de lectura, cuotas de plataforma). |
subscribeSources | Acción | act | Se suscribe a varias fuentes en una sola llamada y devuelve un resultado por fuente. |
unsubscribeSource | Acción | act | Deja de seguir una fuente. Los elementos ya recogidos permanecen en el corpus. |
setHomeDashboard | Acción | act | Define un tablero guardado como página de inicio del workspace. |
upsertSignalRule | Acción | act | Crea o actualiza una regla de señal de persistencia: se activa cuando un elemento permanece en línea más tiempo que el umbral. |
upsertQuestionRule | Acción | act | Crea o actualiza una pregunta permanente: una frase en lenguaje natural que Jev plantea a cada elemento nuevo de las fuentes del workspace. El umbral de probabilidad genera la señal. |
startInvestigation | Acción | act | Pone en cola una investigación de Edge en segundo plano para este workspace (propietario o administrador). |
startHunt | Acción | act | Inicia una búsqueda: encontrar personas que cumplen criterios verificables, cada criterio probado por una fuente pública fechada. Los criterios sensibles se rechazan y no se devuelve ningún dato de contacto. Se ejecuta en segundo plano y consume los créditos del mes; propietario o administrador. |
buildAdAudit | Escritura | write | Auditoría retroactiva de las campañas de 1 a 6 anunciantes ya recogidos, a lo largo de N meses: una tabla del workspace (anunciante, mes, anuncios nuevos, paradas, bibliotecas, países, necesidades leídas, aumento de ritmo) y las cifras de un resumen citado. Sin créditos. |
findCreatorSponsors | Acción | act, write, explore | Quién paga a los creadores de YouTube en un nicho: búsqueda de vídeos recientes, patrocinadores deducidos de cada vídeo, una tabla del workspace «Patrocinadores · nicho». Consume créditos; confirmación en el chat, propietario o administrador. |
importAdHistory | Acción | act, write, explore | Importa el historial de Google de una colección de anunciante: hasta 20 páginas (unos 800 anuncios desde 2021) para fechar campañas pasadas. Consume créditos; confirmación en el chat, propietario o administrador. |
startAdCollection | Acción | act, write, explore | Inicia una recogida de anuncios sobre un anunciante (nombre o dominio) o una palabra clave: lee Meta, TikTok, Google y LinkedIn, pone cada anuncio en el mismo formato y luego lee el ángulo, la oferta, la audiencia y el tono. Consume créditos; confirmación en el chat, propietario o administrador. |