diff --git a/es/features/agent.mdx b/es/features/agent.mdx index 5da9a8b7d..a11c52599 100644 --- a/es/features/agent.mdx +++ b/es/features/agent.mdx @@ -246,6 +246,116 @@ El parámetro `model` es opcional; todas las solicitudes usan `spark-2`: +## Proveedores de datos que requieren términos {#data-providers-that-need-terms} + +Agent puede llamar a proveedores de datos de [Alexandria](/es/features/alexandria) durante una ejecución, pero solo a aquellos cuyos términos de datos haya aceptado tu equipo. Un proveedor cuyos términos no hayas aceptado nunca se llama, sea cual sea el valor de `exchange.onTermsRequired`. La ejecución continúa con los proveedores que puede usar, y la respuesta de estado indica cuáles omitió. + +No existe un modo de aceptación automática. Aceptar los términos de un proveedor siempre requiere que una persona los acepte, ya sea en el [dashboard](https://www.firecrawl.dev/app/settings?tab=data-sources) o mediante una llamada a `terms/accept` que tu aplicación hace después de que su usuario los haya aceptado de forma explícita. Si construyes un agente sobre Firecrawl, debe preguntar a su usuario antes de llamar a `terms/accept`. Una solicitud de datos no equivale a aceptar los términos de un proveedor. + +| `onTermsRequired` | Qué sucede | +|---|---| +| `skip` (predeterminado) | La ejecución responde solo con proveedores aceptados y nunca se bloquea. `exchange.skippedProviders` enumera los proveedores restringidos que habrían ayudado. | +| `ask` | Igual que `skip`. Además, la ejecución termina con `exchange.requiresAction` y un `pendingApproval` de `kind: "terms"`, para que puedas preguntar a tu usuario, aceptar y continuar el hilo. | + +Si omites `onTermsRequired` en un turno de seguimiento de un hilo, el turno usa el valor del turno anterior. Si un turno termina en una aprobación de llamada de pago (`requireApproval`), no incluye ninguna oferta de términos. + +### Campos de la respuesta {#response-fields} + +Estos campos están en el objeto `exchange` de `GET /v2/agent/{id}`: + +- `skippedProviders` (cualquier modo): una entrada por cada proveedor restringido que habría ayudado, con `provider`, `name`, `capability`, `adds` (lo que habría aportado), `reason: "terms_required"`, `version` (la versión de los términos) y `termsUrl` (dónde aceptarlos en el dashboard). +- `requiresAction` (solo `ask`): `type: "accept_terms"`, un `approvalId` y una lista `providers`. `approvalId` siempre está presente: es el id de la aprobación pendiente de tipo `terms` que respondes al continuar el hilo. Cada proveedor incluye las llamadas exactas `show` (`terms/show`) y `accept` (`terms/accept`) que debes hacer. El `digest` de cada proveedor (y `accept.options.digest`) siempre está presente y puede ser `null`, lo que significa que el catálogo no publicó ninguno. En ese caso, ejecuta primero `terms/show` y envía el digest que devuelve. + +```json +{ + "status": "completed", + "exchange": { + "enabled": true, + "onTermsRequired": "ask", + "paidCalls": 0, + "creditsUsed": null, + "skippedProviders": [ + { + "provider": "apollo", + "name": "Apollo", + "capability": "people/search", + "adds": "verified work emails and direct phone numbers", + "reason": "terms_required", + "version": "F-1.0.0", + "termsUrl": "https://www.firecrawl.dev/app/alexandria/apollo" + } + ], + "requiresAction": { + "type": "accept_terms", + "approvalId": "0199aaaa-0000-7000-8000-000000000000", + "providers": [ + { + "provider": "apollo", + "name": "Apollo", + "capability": "people/search", + "version": "F-1.0.0", + "digest": "", + "url": "https://www.firecrawl.dev/app/alexandria/apollo", + "show": { "provider": "firecrawl", "capability": "terms/show", "options": { "provider": "apollo" } }, + "accept": { + "provider": "firecrawl", + "capability": "terms/accept", + "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "", "confirmed": true } + } + } + ] + } + }, + "pendingApproval": { + "id": "0199aaaa-0000-7000-8000-000000000000", + "kind": "terms", + "reason": "Apollo could add verified work emails and direct phone numbers.", + "calls": [], + "terms": [{ "provider": "apollo", "name": "Apollo", "version": "F-1.0.0", "digest": "", "url": "https://www.firecrawl.dev/app/alexandria/apollo" }], + "resolution": null + } +} +``` + +### Aceptar y luego continuar {#accept-then-continue} + +En el modo `ask`: + +1. Muestra los términos a tu usuario. Ejecuta la llamada `show` del proveedor a través de [`/v2/scrape`](/es/features/alexandria) con `alexandria`. +2. Solo si el usuario acepta de forma explícita, ejecuta su llamada `accept` de la misma manera. Si `accept.options.digest` es `null`, usa el digest que devolvió `terms/show`: + +```bash +curl -X POST https://api.firecrawl.dev/v2/scrape \ + -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "alexandria": { + "provider": "firecrawl", + "capability": "terms/accept", + "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "", "confirmed": true } + } + }' +``` + +3. Continúa el mismo hilo con `exchange.approve`. La oferta se acepta en su conjunto, y `callIds` y `always` se ignoran en ella. El siguiente turno usa esos proveedores para cubrir el hueco que señaló la respuesta anterior, en lugar de volver a ejecutarlo todo. + +```bash +curl -X POST https://api.firecrawl.dev/v2/agent \ + -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "threadId": "", + "prompt": "Continue with Apollo.", + "exchange": { + "approve": { "approvalId": "0199aaaa-0000-7000-8000-000000000000" } + } + }' +``` + +Para seguir sin el proveedor, continúa con `exchange.decline: { "approvalId": "..." }`. Esto rechaza la oferta completa, y sus proveedores no se vuelven a ofrecer durante el resto del hilo. + +En el modo `skip` no hay ninguna aprobación pendiente que responder. Una vez aceptados los términos, inicia una nueva ejecución (o un nuevo turno del hilo) y el proveedor estará disponible. + ## Parámetros {#parameters} | Parámetro | Tipo | Obligatorio | Descripción | @@ -258,6 +368,7 @@ El parámetro `model` es opcional; todas las solicitudes usan `spark-2`: | `strictConstrainToURLs` | boolean | No | Si es `true`, el agente solo visita las URLs proporcionadas en el array `urls` | | `webhook` | object | No | Webhook para recibir eventos del ciclo de vida del agente (`agent.started`, `agent.action`, `agent.completed`, `agent.failed`, `agent.cancelled`). Consulta las [cargas útiles de webhook](/es/api-reference/endpoint/webhook-agent-started) | | `maxCredits` | number | No | Número máximo de créditos que se pueden usar en esta tarea del agente. De forma predeterminada es **2,500** si no se especifica. El panel de control admite valores de hasta **2,500**; para límites superiores, configura `maxCredits` mediante la API (los valores por encima de 2,500 siempre se tratan como solicitudes de pago). Si se alcanza el límite, el trabajo falla y **no se devuelve ningún dato**. Las ejecuciones fallidas no se facturan: los créditos usados para el razonamiento de IA nunca se cobran en caso de fallo, cualquier crédito usado para llamadas a herramientas durante la ejecución (`scraping`, `search`, `mapping`, etc.) se reembolsa, y la respuesta informa `creditsUsed: 0`. | +| `exchange.onTermsRequired` | string | No | Qué hacer cuando un proveedor de datos de Alexandria que el agente usaría requiere términos que tu equipo no ha aceptado: `skip` (predeterminado) o `ask`. Consulta [Proveedores de datos que requieren términos](#data-providers-that-need-terms) | ## Agent vs Extract: Qué ha mejorado {#agent-vs-extract-whats-improved} diff --git a/es/features/alexandria.mdx b/es/features/alexandria.mdx index e3cb523bc..19ad0e1b1 100644 --- a/es/features/alexandria.mdx +++ b/es/features/alexandria.mdx @@ -178,7 +178,7 @@ Usa `findTools` / `find_tools` para explorar providers e inspeccionar sus herram * **Descubrimiento de herramientas:** gratis. Usa `sources: ["alexandria"]` solo para herramientas, o `["web", "alexandria"]` para incluir resultados web de pago. * **Ejecución:** se cobra al precio indicado de la herramienta. -* **Términos del provider:** un error `THIRD_PARTY_DATA_TERMS_REQUIRED` incluye `requiresAction.url`. Un administrador de la organización debe revisar y aceptar allí los términos. Los agentes necesitan autorización explícita del usuario antes de aceptar los términos. +* **Términos del provider:** un error `THIRD_PARTY_DATA_TERMS_REQUIRED` incluye `requiresAction.url`. Un administrador de la organización debe revisar y aceptar allí los términos. Los agentes necesitan autorización explícita del usuario antes de aceptar los términos. Las ejecuciones de [Agent](/es/features/agent#data-providers-that-need-terms) omiten los proveedores cuyos términos tu equipo no ha aceptado y los indican en `exchange.skippedProviders`. diff --git a/features/agent.mdx b/features/agent.mdx index 7fc68b158..deafd2e75 100644 --- a/features/agent.mdx +++ b/features/agent.mdx @@ -248,6 +248,116 @@ The `model` parameter is optional — every request runs `spark-2`: +## Data providers that need terms + +Agent can call [Alexandria](/features/alexandria) data providers during a run, but only the ones whose data terms your team has accepted. A provider whose terms you haven't accepted is never called, whatever `exchange.onTermsRequired` is set to. The run carries on with the providers it can use, and the status response reports what it skipped. + +There is no auto-accept mode. Accepting a provider's terms always needs a person to agree to them, either in the [dashboard](https://www.firecrawl.dev/app/settings?tab=data-sources) or through a `terms/accept` call your application makes after its user has explicitly agreed. If you build an agent on top of Firecrawl, it must ask its user before calling `terms/accept`. A request for data isn't consent to a provider's terms. + +| `onTermsRequired` | What happens | +|---|---| +| `skip` (default) | The run answers with accepted providers only and never blocks. `exchange.skippedProviders` lists the gated providers that would have helped. | +| `ask` | The same as `skip`. The run also ends with `exchange.requiresAction` and a `pendingApproval` of `kind: "terms"`, so you can ask your user, accept, and continue the thread. | + +If you leave `onTermsRequired` out on a follow-up turn of a thread, the turn uses the previous turn's value. If a turn ends on a paid-call approval (`requireApproval`), it has no terms offer. + +### Response fields + +These fields are on the `exchange` object of `GET /v2/agent/{id}`: + +- `skippedProviders` (any mode): one entry per gated provider that would have helped, with `provider`, `name`, `capability`, `adds` (what it would have added), `reason: "terms_required"`, `version` (the terms version) and `termsUrl` (where to accept in the dashboard). +- `requiresAction` (`ask` only): `type: "accept_terms"`, an `approvalId` and a `providers` list. `approvalId` is always present. It's the id of the `terms` pending approval you answer when you continue the thread. Each provider carries the exact `show` (`terms/show`) and `accept` (`terms/accept`) calls to make. Each provider's `digest` (and `accept.options.digest`) is always present and can be `null`, meaning the catalog didn't publish one. In that case, run `terms/show` first and send the digest it returns. + +```json +{ + "status": "completed", + "exchange": { + "enabled": true, + "onTermsRequired": "ask", + "paidCalls": 0, + "creditsUsed": null, + "skippedProviders": [ + { + "provider": "apollo", + "name": "Apollo", + "capability": "people/search", + "adds": "verified work emails and direct phone numbers", + "reason": "terms_required", + "version": "F-1.0.0", + "termsUrl": "https://www.firecrawl.dev/app/alexandria/apollo" + } + ], + "requiresAction": { + "type": "accept_terms", + "approvalId": "0199aaaa-0000-7000-8000-000000000000", + "providers": [ + { + "provider": "apollo", + "name": "Apollo", + "capability": "people/search", + "version": "F-1.0.0", + "digest": "", + "url": "https://www.firecrawl.dev/app/alexandria/apollo", + "show": { "provider": "firecrawl", "capability": "terms/show", "options": { "provider": "apollo" } }, + "accept": { + "provider": "firecrawl", + "capability": "terms/accept", + "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "", "confirmed": true } + } + } + ] + } + }, + "pendingApproval": { + "id": "0199aaaa-0000-7000-8000-000000000000", + "kind": "terms", + "reason": "Apollo could add verified work emails and direct phone numbers.", + "calls": [], + "terms": [{ "provider": "apollo", "name": "Apollo", "version": "F-1.0.0", "digest": "", "url": "https://www.firecrawl.dev/app/alexandria/apollo" }], + "resolution": null + } +} +``` + +### Accept, then continue + +In `ask` mode: + +1. Show your user the terms. Run the provider's `show` call through [`/v2/scrape`](/features/alexandria) with `alexandria`. +2. Only if the user explicitly agrees, run its `accept` call the same way. If `accept.options.digest` is `null`, use the digest `terms/show` returned: + +```bash +curl -X POST https://api.firecrawl.dev/v2/scrape \ + -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "alexandria": { + "provider": "firecrawl", + "capability": "terms/accept", + "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "", "confirmed": true } + } + }' +``` + +3. Continue the same thread with `exchange.approve`. The offer is accepted as a whole, and `callIds` and `always` are ignored on it. The next turn uses those providers to fill the gap the previous answer named, rather than re-running everything. + +```bash +curl -X POST https://api.firecrawl.dev/v2/agent \ + -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "threadId": "", + "prompt": "Continue with Apollo.", + "exchange": { + "approve": { "approvalId": "0199aaaa-0000-7000-8000-000000000000" } + } + }' +``` + +To go on without the provider, continue with `exchange.decline: { "approvalId": "..." }` instead. This declines the whole offer, and its providers aren't offered again for the rest of the thread. + +In `skip` mode there's no pending approval to answer. After the terms are accepted, start a new run (or a new turn of the thread) and the provider is available. + ## Parameters | Parameter | Type | Required | Description | @@ -260,6 +370,7 @@ The `model` parameter is optional — every request runs `spark-2`: | `strictConstrainToURLs` | boolean | No | If `true`, the agent only visits the URLs provided in the `urls` array | | `webhook` | object | No | Webhook to receive agent lifecycle events (`agent.started`, `agent.action`, `agent.completed`, `agent.failed`, `agent.cancelled`). See the [webhook payloads](/api-reference/endpoint/webhook-agent-started) | | `maxCredits` | number | No | Maximum number of credits to spend on this agent task. Defaults to **2,500** if not set. The dashboard supports values up to **2,500**; for higher limits, set `maxCredits` via the API (values above 2,500 are always treated as paid requests). If the limit is reached, the job fails and **no data is returned**. Failed runs are not billed: credits used for AI reasoning are never charged on failure, any credits used for tool calls during the run (scraping, search, mapping, etc.) are refunded, and the response reports `creditsUsed: 0`. | +| `exchange.onTermsRequired` | string | No | What to do when an Alexandria data provider the agent would use needs terms your team has not accepted: `skip` (default) or `ask`. See [Data providers that need terms](#data-providers-that-need-terms) | ## Agent vs Extract: What's Improved diff --git a/features/alexandria.mdx b/features/alexandria.mdx index 5eb85aa86..e7e5ed040 100644 --- a/features/alexandria.mdx +++ b/features/alexandria.mdx @@ -176,7 +176,7 @@ if catalogue.items and catalogue.items[0].get("next"): - **Tool discovery:** free. Use `sources: ["alexandria"]` for tools only, or `["web", "alexandria"]` to include paid web results. - **Execution:** charged at the tool's listed price. -- **Provider terms:** a `THIRD_PARTY_DATA_TERMS_REQUIRED` error includes `requiresAction.url`. An org admin must review and accept the terms there. Agents need explicit user authorization before accepting terms. +- **Provider terms:** a `THIRD_PARTY_DATA_TERMS_REQUIRED` error includes `requiresAction.url`. An org admin must review and accept the terms there. Agents need explicit user authorization before accepting terms. [Agent](/features/agent#data-providers-that-need-terms) runs skip providers whose terms your team hasn't accepted and report them in `exchange.skippedProviders`. diff --git a/fr/features/agent.mdx b/fr/features/agent.mdx index f495ea38d..afc3099ac 100644 --- a/fr/features/agent.mdx +++ b/fr/features/agent.mdx @@ -246,6 +246,116 @@ Le paramètre `model` est facultatif : chaque requête utilise `spark-2` : +## Fournisseurs de données soumis à des conditions {#data-providers-that-need-terms} + +Agent peut appeler des fournisseurs de données [Alexandria](/fr/features/alexandria) pendant une exécution, mais uniquement ceux dont votre équipe a accepté les conditions d’utilisation des données. Un fournisseur dont vous n’avez pas accepté les conditions n’est jamais appelé, quelle que soit la valeur de `exchange.onTermsRequired`. L’exécution se poursuit avec les fournisseurs qu’elle peut utiliser, et la réponse de statut indique ceux qu’elle a ignorés. + +Il n’existe aucun mode d’acceptation automatique. L’acceptation des conditions d’un fournisseur nécessite toujours qu’une personne les accepte, soit dans le [dashboard](https://www.firecrawl.dev/app/settings?tab=data-sources), soit via un appel `terms/accept` que votre application effectue après que son utilisateur les a explicitement acceptées. Si vous créez un agent au-dessus de Firecrawl, il doit demander à son utilisateur avant d’appeler `terms/accept`. Une demande de données ne vaut pas acceptation des conditions d’un fournisseur. + +| `onTermsRequired` | Ce qui se passe | +|---|---| +| `skip` (par défaut) | L’exécution répond uniquement avec les fournisseurs acceptés et ne bloque jamais. `exchange.skippedProviders` liste les fournisseurs soumis à conditions qui auraient été utiles. | +| `ask` | Comme `skip`. L’exécution se termine en plus avec `exchange.requiresAction` et un `pendingApproval` de `kind: "terms"`, pour que vous puissiez demander à votre utilisateur, accepter et poursuivre le fil. | + +Si vous omettez `onTermsRequired` lors d’un tour suivant d’un fil, le tour reprend la valeur du tour précédent. Si un tour se termine sur une approbation d’appel payant (`requireApproval`), il ne contient aucune offre de conditions. + +### Champs de la réponse {#response-fields} + +Ces champs se trouvent dans l’objet `exchange` de `GET /v2/agent/{id}` : + +- `skippedProviders` (tous les modes) : une entrée par fournisseur soumis à conditions qui aurait été utile, avec `provider`, `name`, `capability`, `adds` (ce qu’il aurait apporté), `reason: "terms_required"`, `version` (la version des conditions) et `termsUrl` (où les accepter dans le dashboard). +- `requiresAction` (`ask` uniquement) : `type: "accept_terms"`, un `approvalId` et une liste `providers`. `approvalId` est toujours présent : c’est l’id de l’approbation en attente de type `terms` à laquelle vous répondez en poursuivant le fil. Chaque fournisseur contient les appels exacts `show` (`terms/show`) et `accept` (`terms/accept`) à effectuer. Le `digest` de chaque fournisseur (et `accept.options.digest`) est toujours présent et peut valoir `null`, ce qui signifie que le catalogue n’en a publié aucun. Dans ce cas, exécutez d’abord `terms/show` et envoyez le digest qu’il renvoie. + +```json +{ + "status": "completed", + "exchange": { + "enabled": true, + "onTermsRequired": "ask", + "paidCalls": 0, + "creditsUsed": null, + "skippedProviders": [ + { + "provider": "apollo", + "name": "Apollo", + "capability": "people/search", + "adds": "verified work emails and direct phone numbers", + "reason": "terms_required", + "version": "F-1.0.0", + "termsUrl": "https://www.firecrawl.dev/app/alexandria/apollo" + } + ], + "requiresAction": { + "type": "accept_terms", + "approvalId": "0199aaaa-0000-7000-8000-000000000000", + "providers": [ + { + "provider": "apollo", + "name": "Apollo", + "capability": "people/search", + "version": "F-1.0.0", + "digest": "", + "url": "https://www.firecrawl.dev/app/alexandria/apollo", + "show": { "provider": "firecrawl", "capability": "terms/show", "options": { "provider": "apollo" } }, + "accept": { + "provider": "firecrawl", + "capability": "terms/accept", + "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "", "confirmed": true } + } + } + ] + } + }, + "pendingApproval": { + "id": "0199aaaa-0000-7000-8000-000000000000", + "kind": "terms", + "reason": "Apollo could add verified work emails and direct phone numbers.", + "calls": [], + "terms": [{ "provider": "apollo", "name": "Apollo", "version": "F-1.0.0", "digest": "", "url": "https://www.firecrawl.dev/app/alexandria/apollo" }], + "resolution": null + } +} +``` + +### Accepter, puis poursuivre {#accept-then-continue} + +En mode `ask` : + +1. Montrez les conditions à votre utilisateur. Exécutez l’appel `show` du fournisseur via [`/v2/scrape`](/fr/features/alexandria) avec `alexandria`. +2. Uniquement si l’utilisateur les accepte explicitement, exécutez son appel `accept` de la même façon. Si `accept.options.digest` vaut `null`, utilisez le digest renvoyé par `terms/show` : + +```bash +curl -X POST https://api.firecrawl.dev/v2/scrape \ + -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "alexandria": { + "provider": "firecrawl", + "capability": "terms/accept", + "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "", "confirmed": true } + } + }' +``` + +3. Poursuivez le même fil avec `exchange.approve`. L’offre est acceptée dans son ensemble, et `callIds` et `always` y sont ignorés. Le tour suivant utilise ces fournisseurs pour combler le manque signalé par la réponse précédente, au lieu de tout relancer. + +```bash +curl -X POST https://api.firecrawl.dev/v2/agent \ + -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "threadId": "", + "prompt": "Continue with Apollo.", + "exchange": { + "approve": { "approvalId": "0199aaaa-0000-7000-8000-000000000000" } + } + }' +``` + +Pour continuer sans le fournisseur, poursuivez plutôt avec `exchange.decline: { "approvalId": "..." }`. L’offre entière est alors refusée, et ses fournisseurs ne sont plus proposés pour le reste du fil. + +En mode `skip`, il n’y a aucune approbation en attente à laquelle répondre. Une fois les conditions acceptées, lancez une nouvelle exécution (ou un nouveau tour du fil) et le fournisseur est disponible. + ## Paramètres {#parameters} | Paramètre | Type | Requis | Description | @@ -258,6 +368,7 @@ Le paramètre `model` est facultatif : chaque requête utilise `spark-2` : | `strictConstrainToURLs` | boolean | Non | Si `true`, l’agent visite uniquement les URL fournies dans le tableau `urls` | | `webhook` | object | Non | Webhook pour recevoir les événements du cycle de vie de l’agent (`agent.started`, `agent.action`, `agent.completed`, `agent.failed`, `agent.cancelled`). Consultez les [charges utiles de webhook](/fr/api-reference/endpoint/webhook-agent-started) | | `maxCredits` | number | Non | Nombre maximal de crédits à dépenser pour cette tâche d’agent. La valeur par défaut est **2 500** s’il n’est pas défini. Le tableau de bord prend en charge des valeurs jusqu’à **2 500** ; pour des limites plus élevées, définissez `maxCredits` via l’API (les valeurs supérieures à 2 500 sont toujours traitées comme des requêtes payantes). Si la limite est atteinte, la tâche échoue et **aucune donnée n’est renvoyée**. Les exécutions en échec ne sont pas facturées : les crédits utilisés pour le raisonnement de l’IA ne sont jamais facturés en cas d’échec, tous les crédits utilisés pour les appels d’outils pendant l’exécution (scraping, recherche, mapping, etc.) sont remboursés, et la réponse indique `creditsUsed: 0`. | +| `exchange.onTermsRequired` | string | Non | Que faire lorsqu’un fournisseur de données Alexandria que l’agent utiliserait exige des conditions que votre équipe n’a pas acceptées : `skip` (par défaut) ou `ask`. Voir [Fournisseurs de données soumis à des conditions](#data-providers-that-need-terms) | ## Agent vs Extract : ce qui a été amélioré {#agent-vs-extract-whats-improved} diff --git a/fr/features/alexandria.mdx b/fr/features/alexandria.mdx index 52ef82413..11658b5ce 100644 --- a/fr/features/alexandria.mdx +++ b/fr/features/alexandria.mdx @@ -178,7 +178,7 @@ Utilisez `findTools` / `find_tools` pour parcourir les providers et inspecter le * **Découverte des outils :** gratuite. Utilisez `sources: ["alexandria"]` pour les outils uniquement, ou `["web", "alexandria"]` pour inclure les résultats web payants. * **Exécution :** facturée au prix indiqué de l'outil. -* **Conditions du provider :** une erreur `THIRD_PARTY_DATA_TERMS_REQUIRED` contient `requiresAction.url`. Un administrateur de l'organisation doit y consulter et accepter les conditions. Les agents doivent obtenir une autorisation explicite de l'utilisateur avant d'accepter ces conditions. +* **Conditions du provider :** une erreur `THIRD_PARTY_DATA_TERMS_REQUIRED` contient `requiresAction.url`. Un administrateur de l'organisation doit y consulter et accepter les conditions. Les agents doivent obtenir une autorisation explicite de l'utilisateur avant d'accepter ces conditions. Les exécutions [Agent](/fr/features/agent#data-providers-that-need-terms) ignorent les fournisseurs dont votre équipe n’a pas accepté les conditions et les signalent dans `exchange.skippedProviders`. diff --git a/ja/features/agent.mdx b/ja/features/agent.mdx index f8688beb1..e71e7b946 100644 --- a/ja/features/agent.mdx +++ b/ja/features/agent.mdx @@ -246,6 +246,116 @@ Firecrawl Agent は **Spark 2** で動作します。Spark 2 は、同等の精 +## 規約への同意が必要なデータプロバイダー {#data-providers-that-need-terms} + +Agent は実行中に [Alexandria](/ja/features/alexandria) のデータプロバイダーを呼び出せますが、呼び出すのはチームがデータ規約に同意したプロバイダーだけです。規約に同意していないプロバイダーは、`exchange.onTermsRequired` の設定にかかわらず呼び出されません。実行は利用できるプロバイダーで続行され、スキップしたプロバイダーはステータスのレスポンスで報告されます。 + +自動同意モードはありません。プロバイダーの規約への同意には、必ず人による同意が必要です。同意は [ダッシュボード](https://www.firecrawl.dev/app/settings?tab=data-sources) で行うか、アプリケーションがユーザーの明示的な同意を得たうえで `terms/accept` を呼び出して行います。Firecrawl の上にエージェントを構築する場合、そのエージェントは `terms/accept` を呼び出す前にユーザーに確認する必要があります。データのリクエストは、プロバイダーの規約への同意にはあたりません。 + +| `onTermsRequired` | 動作 | +|---|---| +| `skip`（デフォルト） | 同意済みのプロバイダーだけで回答し、処理がブロックされることはありません。`exchange.skippedProviders` に、役立ったはずの規約未同意のプロバイダーが一覧表示されます。 | +| `ask` | `skip` と同じ動作に加えて、実行は `exchange.requiresAction` と `kind: "terms"` の `pendingApproval` で終了します。ユーザーに確認して同意し、スレッドを続行できます。 | + +スレッドのフォローアップのターンで `onTermsRequired` を省略すると、前のターンの値が使われます。ターンが有料呼び出しの承認（`requireApproval`）で終了した場合、そのターンに規約のオファーは含まれません。 + +### レスポンスのフィールド {#response-fields} + +これらのフィールドは `GET /v2/agent/{id}` の `exchange` オブジェクトに含まれます。 + +- `skippedProviders`（すべてのモード）: 役立ったはずの規約未同意のプロバイダーごとに 1 件ずつ、`provider`、`name`、`capability`、`adds`（追加できたはずの内容）、`reason: "terms_required"`、`version`（規約のバージョン）、`termsUrl`（ダッシュボードで同意する場所）を含むエントリーが入ります。 +- `requiresAction`（`ask` のみ）: `type: "accept_terms"`、`approvalId`、`providers` のリスト。`approvalId` は常に含まれ、スレッドを続行するときに応答する `terms` の保留中の承認の id です。各プロバイダーには、実行すべき `show`（`terms/show`）と `accept`（`terms/accept`）の呼び出しがそのまま含まれます。各プロバイダーの `digest`（および `accept.options.digest`）は常に含まれ、`null` の場合があります。これはカタログが digest を公開していないことを意味します。その場合は、先に `terms/show` を実行し、返された digest を送信してください。 + +```json +{ + "status": "completed", + "exchange": { + "enabled": true, + "onTermsRequired": "ask", + "paidCalls": 0, + "creditsUsed": null, + "skippedProviders": [ + { + "provider": "apollo", + "name": "Apollo", + "capability": "people/search", + "adds": "verified work emails and direct phone numbers", + "reason": "terms_required", + "version": "F-1.0.0", + "termsUrl": "https://www.firecrawl.dev/app/alexandria/apollo" + } + ], + "requiresAction": { + "type": "accept_terms", + "approvalId": "0199aaaa-0000-7000-8000-000000000000", + "providers": [ + { + "provider": "apollo", + "name": "Apollo", + "capability": "people/search", + "version": "F-1.0.0", + "digest": "", + "url": "https://www.firecrawl.dev/app/alexandria/apollo", + "show": { "provider": "firecrawl", "capability": "terms/show", "options": { "provider": "apollo" } }, + "accept": { + "provider": "firecrawl", + "capability": "terms/accept", + "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "", "confirmed": true } + } + } + ] + } + }, + "pendingApproval": { + "id": "0199aaaa-0000-7000-8000-000000000000", + "kind": "terms", + "reason": "Apollo could add verified work emails and direct phone numbers.", + "calls": [], + "terms": [{ "provider": "apollo", "name": "Apollo", "version": "F-1.0.0", "digest": "", "url": "https://www.firecrawl.dev/app/alexandria/apollo" }], + "resolution": null + } +} +``` + +### 同意してから続行する {#accept-then-continue} + +`ask` モードの場合: + +1. ユーザーに規約を表示します。プロバイダーの `show` 呼び出しを、`alexandria` を指定して [`/v2/scrape`](/ja/features/alexandria) で実行します。 +2. ユーザーが明示的に同意した場合に限り、同じ方法で `accept` 呼び出しを実行します。`accept.options.digest` が `null` の場合は、`terms/show` が返した digest を使います。 + +```bash +curl -X POST https://api.firecrawl.dev/v2/scrape \ + -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "alexandria": { + "provider": "firecrawl", + "capability": "terms/accept", + "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "", "confirmed": true } + } + }' +``` + +3. `exchange.approve` で同じスレッドを続行します。オファーはまとめて承認され、`callIds` と `always` は無視されます。次のターンでは、すべてを再実行するのではなく、前の回答が示した不足分をそれらのプロバイダーで補います。 + +```bash +curl -X POST https://api.firecrawl.dev/v2/agent \ + -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "threadId": "", + "prompt": "Continue with Apollo.", + "exchange": { + "approve": { "approvalId": "0199aaaa-0000-7000-8000-000000000000" } + } + }' +``` + +プロバイダーを使わずに進める場合は、代わりに `exchange.decline: { "approvalId": "..." }` で続行します。これによりオファー全体が辞退され、そのプロバイダーはスレッドの残りの期間、再びオファーされません。 + +`skip` モードでは、応答すべき保留中の承認はありません。規約に同意したら、新しい実行（またはスレッドの新しいターン）を開始すると、そのプロバイダーを利用できます。 + ## パラメータ {#parameters} | パラメータ | Type | Required | Description | @@ -258,6 +368,7 @@ Firecrawl Agent は **Spark 2** で動作します。Spark 2 は、同等の精 | `strictConstrainToURLs` | boolean | No | `true` の場合、エージェントは `urls` 配列で指定された URL のみを訪問します | | `webhook` | object | No | エージェントのライフサイクルイベント (`agent.started`、`agent.action`、`agent.completed`、`agent.failed`、`agent.cancelled`) を受信する webhook。[webhook ペイロード](/ja/api-reference/endpoint/webhook-agent-started)を参照してください | | `maxCredits` | number | No | このエージェントタスクで使用するクレジットの最大数。設定しない場合、デフォルトは **2,500** です。ダッシュボードでは **2,500** までの値をサポートしています。これを超える上限を設定するには、API 経由で `maxCredits` を指定してください (2,500 を超える値は常に有料リクエストとして扱われます)。上限に達するとジョブは失敗し、**データは一切返されません**。失敗した実行には課金されません。AI の推論に使用されたクレジットは失敗時には請求されず、実行中のツール呼び出し (`scraping`、`search`、`mapping` など) に使用されたクレジットは返還され、レスポンスには `creditsUsed: 0` が記録されます。 | +| `exchange.onTermsRequired` | string | No | エージェントが使う Alexandria のデータプロバイダーが、チームが同意していない規約を必要とする場合の動作: `skip`（デフォルト）または `ask`。[規約への同意が必要なデータプロバイダー](#data-providers-that-need-terms) を参照してください | ## Agent と Extract：何が改善されたか {#agent-vs-extract-whats-improved} diff --git a/ja/features/alexandria.mdx b/ja/features/alexandria.mdx index 9c95fc52f..b83fa7aed 100644 --- a/ja/features/alexandria.mdx +++ b/ja/features/alexandria.mdx @@ -178,7 +178,7 @@ Alexandria は、Firecrawl を通じてエージェントに structured data へ * **ツールのディスカバリー:** 無料。ツールのみを取得する場合は `sources: ["alexandria"]`、有料の Web 結果も含める場合は `["web", "alexandria"]` を使用します。 * **実行:** ツールに記載された価格で課金されます。 -* **プロバイダーの規約:** `THIRD_PARTY_DATA_TERMS_REQUIRED` エラーには `requiresAction.url` が含まれます。組織の管理者がそのページで規約を確認し、承諾する必要があります。Agentが規約を承諾するには、ユーザーによる明示的な認可が必要です。 +* **プロバイダーの規約:** `THIRD_PARTY_DATA_TERMS_REQUIRED` エラーには `requiresAction.url` が含まれます。組織の管理者がそのページで規約を確認し、承諾する必要があります。Agentが規約を承諾するには、ユーザーによる明示的な認可が必要です。[Agent](/ja/features/agent#data-providers-that-need-terms) の実行では、チームが規約に同意していないプロバイダーはスキップされ、`exchange.skippedProviders` で報告されます。 diff --git a/pt-BR/features/agent.mdx b/pt-BR/features/agent.mdx index ab56b0147..4e943cd39 100644 --- a/pt-BR/features/agent.mdx +++ b/pt-BR/features/agent.mdx @@ -246,6 +246,116 @@ O parâmetro `model` é opcional — todas as solicitações usam `spark-2`: +## Provedores de dados que exigem termos {#data-providers-that-need-terms} + +O Agent pode chamar provedores de dados do [Alexandria](/pt-BR/features/alexandria) durante uma execução, mas apenas aqueles cujos termos de dados sua equipe aceitou. Um provedor cujos termos você não aceitou nunca é chamado, independentemente do valor de `exchange.onTermsRequired`. A execução continua com os provedores que pode usar, e a resposta de status informa quais foram ignorados. + +Não existe um modo de aceitação automática. Aceitar os termos de um provedor sempre exige que uma pessoa concorde com eles, seja no [dashboard](https://www.firecrawl.dev/app/settings?tab=data-sources) ou por meio de uma chamada `terms/accept` que sua aplicação faz depois que o usuário concordou explicitamente. Se você cria um agente sobre o Firecrawl, ele deve perguntar ao usuário antes de chamar `terms/accept`. Uma solicitação de dados não equivale a concordar com os termos de um provedor. + +| `onTermsRequired` | O que acontece | +|---|---| +| `skip` (padrão) | A execução responde apenas com provedores aceitos e nunca bloqueia. `exchange.skippedProviders` lista os provedores restritos que teriam ajudado. | +| `ask` | O mesmo que `skip`. Além disso, a execução termina com `exchange.requiresAction` e um `pendingApproval` de `kind: "terms"`, para que você possa perguntar ao usuário, aceitar e continuar a thread. | + +Se você omitir `onTermsRequired` em um turno de acompanhamento de uma thread, o turno usa o valor do turno anterior. Se um turno terminar em uma aprovação de chamada paga (`requireApproval`), ele não inclui oferta de termos. + +### Campos da resposta {#response-fields} + +Estes campos ficam no objeto `exchange` de `GET /v2/agent/{id}`: + +- `skippedProviders` (qualquer modo): uma entrada para cada provedor restrito que teria ajudado, com `provider`, `name`, `capability`, `adds` (o que ele teria acrescentado), `reason: "terms_required"`, `version` (a versão dos termos) e `termsUrl` (onde aceitá-los no dashboard). +- `requiresAction` (apenas `ask`): `type: "accept_terms"`, um `approvalId` e uma lista `providers`. `approvalId` está sempre presente: é o id da aprovação pendente do tipo `terms` que você responde ao continuar a thread. Cada provedor traz as chamadas exatas `show` (`terms/show`) e `accept` (`terms/accept`) a fazer. O `digest` de cada provedor (e `accept.options.digest`) está sempre presente e pode ser `null`, o que significa que o catálogo não publicou nenhum. Nesse caso, execute `terms/show` primeiro e envie o digest que ele retornar. + +```json +{ + "status": "completed", + "exchange": { + "enabled": true, + "onTermsRequired": "ask", + "paidCalls": 0, + "creditsUsed": null, + "skippedProviders": [ + { + "provider": "apollo", + "name": "Apollo", + "capability": "people/search", + "adds": "verified work emails and direct phone numbers", + "reason": "terms_required", + "version": "F-1.0.0", + "termsUrl": "https://www.firecrawl.dev/app/alexandria/apollo" + } + ], + "requiresAction": { + "type": "accept_terms", + "approvalId": "0199aaaa-0000-7000-8000-000000000000", + "providers": [ + { + "provider": "apollo", + "name": "Apollo", + "capability": "people/search", + "version": "F-1.0.0", + "digest": "", + "url": "https://www.firecrawl.dev/app/alexandria/apollo", + "show": { "provider": "firecrawl", "capability": "terms/show", "options": { "provider": "apollo" } }, + "accept": { + "provider": "firecrawl", + "capability": "terms/accept", + "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "", "confirmed": true } + } + } + ] + } + }, + "pendingApproval": { + "id": "0199aaaa-0000-7000-8000-000000000000", + "kind": "terms", + "reason": "Apollo could add verified work emails and direct phone numbers.", + "calls": [], + "terms": [{ "provider": "apollo", "name": "Apollo", "version": "F-1.0.0", "digest": "", "url": "https://www.firecrawl.dev/app/alexandria/apollo" }], + "resolution": null + } +} +``` + +### Aceitar e depois continuar {#accept-then-continue} + +No modo `ask`: + +1. Mostre os termos ao usuário. Execute a chamada `show` do provedor por meio de [`/v2/scrape`](/pt-BR/features/alexandria) com `alexandria`. +2. Somente se o usuário concordar explicitamente, execute a chamada `accept` da mesma forma. Se `accept.options.digest` for `null`, use o digest retornado por `terms/show`: + +```bash +curl -X POST https://api.firecrawl.dev/v2/scrape \ + -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "alexandria": { + "provider": "firecrawl", + "capability": "terms/accept", + "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "", "confirmed": true } + } + }' +``` + +3. Continue a mesma thread com `exchange.approve`. A oferta é aceita como um todo, e `callIds` e `always` são ignorados nela. O próximo turno usa esses provedores para preencher a lacuna apontada pela resposta anterior, em vez de executar tudo de novo. + +```bash +curl -X POST https://api.firecrawl.dev/v2/agent \ + -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "threadId": "", + "prompt": "Continue with Apollo.", + "exchange": { + "approve": { "approvalId": "0199aaaa-0000-7000-8000-000000000000" } + } + }' +``` + +Para seguir sem o provedor, continue com `exchange.decline: { "approvalId": "..." }`. Isso recusa a oferta inteira, e seus provedores não são oferecidos novamente pelo resto da thread. + +No modo `skip` não há aprovação pendente para responder. Depois que os termos forem aceitos, inicie uma nova execução (ou um novo turno da thread) e o provedor estará disponível. + ## Parâmetros {#parameters} | Parâmetro | Tipo | Obrigatório | Descrição | @@ -258,6 +368,7 @@ O parâmetro `model` é opcional — todas as solicitações usam `spark-2`: | `strictConstrainToURLs` | boolean | Não | Se `true`, o agente visita apenas as URLs fornecidas no array `urls` | | `webhook` | object | Não | Webhook para receber eventos do ciclo de vida do agente (`agent.started`, `agent.action`, `agent.completed`, `agent.failed`, `agent.cancelled`). Consulte os [payloads de webhook](/pt-BR/api-reference/endpoint/webhook-agent-started) | | `maxCredits` | number | Não | Número máximo de créditos a serem usados nesta tarefa de agente. O padrão é **2.500** se não for definido. O painel suporta valores de até **2.500**; para limites mais altos, defina `maxCredits` via API (valores acima de 2.500 são sempre tratados como requisições pagas). Se o limite for atingido, o job falha e **nenhum dado é retornado**. Execuções com falha não são cobradas: créditos usados para raciocínio de IA nunca são cobrados em caso de falha, quaisquer créditos usados para chamadas de ferramentas durante a execução (scraping, busca, mapeamento etc.) são reembolsados, e a resposta informa `creditsUsed: 0`. | +| `exchange.onTermsRequired` | string | Não | O que fazer quando um provedor de dados do Alexandria que o agente usaria exige termos que sua equipe não aceitou: `skip` (padrão) ou `ask`. Veja [Provedores de dados que exigem termos](#data-providers-that-need-terms) | ## Agent vs Extract: O que melhorou {#agent-vs-extract-whats-improved} diff --git a/pt-BR/features/alexandria.mdx b/pt-BR/features/alexandria.mdx index 25fc84480..e55a1c11b 100644 --- a/pt-BR/features/alexandria.mdx +++ b/pt-BR/features/alexandria.mdx @@ -178,7 +178,7 @@ Use `findTools` / `find_tools` para explorar os providers e inspecionar suas fer * **Descoberta de ferramentas:** gratuita. Use `sources: ["alexandria"]` para obter apenas ferramentas, ou `["web", "alexandria"]` para incluir resultados da web pagos. * **Execução:** cobrada pelo preço listado da ferramenta. -* **Termos do provider:** um erro `THIRD_PARTY_DATA_TERMS_REQUIRED` inclui `requiresAction.url`. Um administrador da organização deve revisar e aceitar os termos nesse endereço. Agentes precisam de autorização explícita do usuário antes de aceitar os termos. +* **Termos do provider:** um erro `THIRD_PARTY_DATA_TERMS_REQUIRED` inclui `requiresAction.url`. Um administrador da organização deve revisar e aceitar os termos nesse endereço. Agentes precisam de autorização explícita do usuário antes de aceitar os termos. As execuções do [Agent](/pt-BR/features/agent#data-providers-that-need-terms) ignoram provedores cujos termos sua equipe não aceitou e os informam em `exchange.skippedProviders`. diff --git a/zh/features/agent.mdx b/zh/features/agent.mdx index bcc1eacf4..ced2ad06d 100644 --- a/zh/features/agent.mdx +++ b/zh/features/agent.mdx @@ -246,6 +246,116 @@ Firecrawl 代理使用 **Spark 2**，相比早期的 Spark 1 模型成本更低 +## 需要接受条款的数据提供商 {#data-providers-that-need-terms} + +Agent 在运行过程中可以调用 [Alexandria](/zh/features/alexandria) 数据提供商，但只会调用你的团队已接受其数据条款的提供商。无论 `exchange.onTermsRequired` 设置为何值，都不会调用你尚未接受条款的提供商。运行会继续使用可用的提供商，并在状态响应中报告跳过了哪些提供商。 + +没有自动接受模式。接受提供商的条款始终需要由人来同意：可以在 [控制台](https://www.firecrawl.dev/app/settings?tab=data-sources) 中完成，也可以由你的应用在用户明确同意后调用 `terms/accept` 完成。如果你在 Firecrawl 之上构建代理，它必须在调用 `terms/accept` 之前征得用户同意。请求数据并不等于同意提供商的条款。 + +| `onTermsRequired` | 行为 | +|---|---| +| `skip`（默认） | 运行仅使用已接受的提供商作答，且不会阻塞。`exchange.skippedProviders` 会列出本可提供帮助、但需要接受条款的提供商。 | +| `ask` | 与 `skip` 相同。此外，运行结束时会返回 `exchange.requiresAction` 以及一个 `kind: "terms"` 的 `pendingApproval`，便于你询问用户、接受条款并继续该线程。 | + +如果你在线程的后续轮次中省略 `onTermsRequired`，该轮次会沿用上一轮的值。如果某一轮以付费调用审批（`requireApproval`）结束，则该轮不会包含条款请求。 + +### 响应字段 {#response-fields} + +这些字段位于 `GET /v2/agent/{id}` 返回的 `exchange` 对象中： + +- `skippedProviders`（所有模式）：每个本可提供帮助、但需要接受条款的提供商对应一条记录，包含 `provider`、`name`、`capability`、`adds`（它本可补充的内容）、`reason: "terms_required"`、`version`（条款版本）和 `termsUrl`（在控制台中接受条款的位置）。 +- `requiresAction`（仅 `ask`）：包含 `type: "accept_terms"`、一个 `approvalId` 和一个 `providers` 列表。`approvalId` 始终存在，它是你继续线程时要答复的 `terms` 待审批项的 id。每个提供商都附带需要执行的完整 `show`（`terms/show`）和 `accept`（`terms/accept`）调用。每个提供商的 `digest`（以及 `accept.options.digest`）始终存在，值可能为 `null`，表示目录未发布摘要。此时请先运行 `terms/show`，再发送它返回的 digest。 + +```json +{ + "status": "completed", + "exchange": { + "enabled": true, + "onTermsRequired": "ask", + "paidCalls": 0, + "creditsUsed": null, + "skippedProviders": [ + { + "provider": "apollo", + "name": "Apollo", + "capability": "people/search", + "adds": "verified work emails and direct phone numbers", + "reason": "terms_required", + "version": "F-1.0.0", + "termsUrl": "https://www.firecrawl.dev/app/alexandria/apollo" + } + ], + "requiresAction": { + "type": "accept_terms", + "approvalId": "0199aaaa-0000-7000-8000-000000000000", + "providers": [ + { + "provider": "apollo", + "name": "Apollo", + "capability": "people/search", + "version": "F-1.0.0", + "digest": "", + "url": "https://www.firecrawl.dev/app/alexandria/apollo", + "show": { "provider": "firecrawl", "capability": "terms/show", "options": { "provider": "apollo" } }, + "accept": { + "provider": "firecrawl", + "capability": "terms/accept", + "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "", "confirmed": true } + } + } + ] + } + }, + "pendingApproval": { + "id": "0199aaaa-0000-7000-8000-000000000000", + "kind": "terms", + "reason": "Apollo could add verified work emails and direct phone numbers.", + "calls": [], + "terms": [{ "provider": "apollo", "name": "Apollo", "version": "F-1.0.0", "digest": "", "url": "https://www.firecrawl.dev/app/alexandria/apollo" }], + "resolution": null + } +} +``` + +### 接受后继续 {#accept-then-continue} + +在 `ask` 模式下： + +1. 向用户展示条款。通过 [`/v2/scrape`](/zh/features/alexandria) 并使用 `alexandria` 运行该提供商的 `show` 调用。 +2. 仅在用户明确同意后，以同样方式运行其 `accept` 调用。如果 `accept.options.digest` 为 `null`，请使用 `terms/show` 返回的 digest： + +```bash +curl -X POST https://api.firecrawl.dev/v2/scrape \ + -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "alexandria": { + "provider": "firecrawl", + "capability": "terms/accept", + "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "", "confirmed": true } + } + }' +``` + +3. 使用 `exchange.approve` 继续同一线程。条款请求作为一个整体被接受，其中的 `callIds` 和 `always` 会被忽略。下一轮会使用这些提供商补齐上一次回答指出的缺口，而不是重新执行全部内容。 + +```bash +curl -X POST https://api.firecrawl.dev/v2/agent \ + -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "threadId": "", + "prompt": "Continue with Apollo.", + "exchange": { + "approve": { "approvalId": "0199aaaa-0000-7000-8000-000000000000" } + } + }' +``` + +如果不使用该提供商继续，请改用 `exchange.decline: { "approvalId": "..." }` 继续。这会拒绝整个条款请求，在该线程余下的轮次中不会再次提供这些提供商。 + +在 `skip` 模式下，没有需要答复的待审批项。接受条款后，发起新的运行（或线程的新一轮），即可使用该提供商。 + ## 参数 {#parameters} | 参数 | 类型 | 必填 | 描述 | @@ -258,6 +368,7 @@ Firecrawl 代理使用 **Spark 2**，相比早期的 Spark 1 模型成本更低 | `strictConstrainToURLs` | boolean | 否 | 如果为 `true`，代理仅访问 `urls` array 中提供的 URL | | `webhook` | object | 否 | 用于接收代理生命周期事件 (`agent.started`、`agent.action`、`agent.completed`、`agent.failed`、`agent.cancelled`) 的 Webhook。请参见 [webhook payloads](/zh/api-reference/endpoint/webhook-agent-started) | | `maxCredits` | number | 否 | 此代理任务中可花费的最大额度数。如果未设置，默认值为 **2,500**。Dashboard 最高支持 **2,500**；如需更高上限，请通过 API 设置 `maxCredits` (高于 2,500 的值始终按付费请求处理) 。如果达到上限，任务会失败，并且**不会返回任何数据**。失败的运行不会计费：用于 AI 推理的额度在失败时绝不会收费，运行期间任何用于工具调用的额度 (scraping、search、mapping 等) 都会退还，并且响应会返回 `creditsUsed: 0`。 | +| `exchange.onTermsRequired` | string | 否 | 当代理要使用的 Alexandria 数据提供商需要你的团队尚未接受的条款时的处理方式：`skip`（默认）或 `ask`。参见 [需要接受条款的数据提供商](#data-providers-that-need-terms) | ## Agent 与 Extract：有哪些改进 {#agent-vs-extract-whats-improved} diff --git a/zh/features/alexandria.mdx b/zh/features/alexandria.mdx index 4bca37bbe..301ca9b14 100644 --- a/zh/features/alexandria.mdx +++ b/zh/features/alexandria.mdx @@ -178,7 +178,7 @@ Alexandria 让代理通过 Firecrawl 访问结构化数据。发现工具、查 * **工具发现：** 免费。使用 `sources: ["alexandria"]` 仅获取工具，或使用 `["web", "alexandria"]` 同时包含付费的网页结果。 * **执行：** 按工具标价计费。 -* **提供商条款：** `THIRD_PARTY_DATA_TERMS_REQUIRED` 错误中会包含 `requiresAction.url`。组织管理员需在该页面查看并接受条款。代理在接受条款前须获得用户的明确授权。 +* **提供商条款：** `THIRD_PARTY_DATA_TERMS_REQUIRED` 错误中会包含 `requiresAction.url`。组织管理员需在该页面查看并接受条款。代理在接受条款前须获得用户的明确授权。[Agent](/zh/features/agent#data-providers-that-need-terms) 运行会跳过你的团队尚未接受条款的提供商，并在 `exchange.skippedProviders` 中报告。