> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-capy-docs-factual-copy-fixes.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Agente > Você é um agente de IA que precisa de uma chave de API da Firecrawl? Veja [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para instruções automatizadas de integração. ## OpenAPI ````yaml pt-BR/api-reference/v2-openapi.json POST /agent openapi: 3.0.0 info: contact: email: support@firecrawl.dev name: Firecrawl Support url: https://firecrawl.dev/support description: >- API para interagir com os serviços do Firecrawl e executar tarefas de web scraping e crawling. title: Firecrawl API version: v2 servers: - url: https://api.firecrawl.dev/v2 security: - bearerAuth: [] paths: /agent: post: tags: - Agent summary: Iniciar uma tarefa de agente para extração de dados orientada a agentes operationId: startAgent requestBody: content: application/json: schema: properties: auditMetadata: $ref: '#/components/schemas/AuditMetadata' effort: description: >- Orçamento de raciocínio para a tarefa do agente. Todas as execuções são realizadas no spark-2, portanto o esforço pode ser enviado com ou sem modelo. enum: - low - medium - high type: string exchange: additionalProperties: false description: >- Permita que o agente chame os providers de dados da sua equipe no [Alexandria](https://docs.firecrawl.dev/features/alexandria) durante a execução. Sem este object, a execução usa apenas a web (um turno de acompanhamento herda as configurações do turno anterior). Consulte [Use suas ferramentas conectadas do Alexandria](https://docs.firecrawl.dev/features/agent#use-your-connected-alexandria-tools). properties: approve: additionalProperties: false description: >- Responda sim à `pendingApproval` gerada ao final do turno anterior desta conversa. Exige `threadId`. properties: always: default: false description: >- Pare de pedir aprovação até o fim da conversa. Ignorado em uma aprovação do tipo `terms`. type: boolean approvalId: description: O `pendingApproval.id` ao qual responder. format: uuid type: string callIds: description: >- Execute apenas estas chamadas entre as que aguardam aprovação. O padrão é executar todas. Ignorado em uma aprovação do tipo `terms`. items: type: string type: array required: - approvalId type: object decline: additionalProperties: false description: >- Responda não à `pendingApproval` gerada ao final do turno anterior desta conversa. Exige `threadId`. Recusar uma oferta de `terms` impede o uso dos providers associados até o fim da conversa. properties: approvalId: description: O `pendingApproval.id` ao qual responder. format: uuid type: string required: - approvalId type: object enabled: default: true description: >- Permita que o agente chame providers do Alexandria. O padrão é `true` quando `exchange` é enviado; envie `false` para desativar os providers em um turno da conversa. type: boolean maxCalls: default: 16 description: >- Número máximo de chamadas a providers que o agente pode fazer neste turno. maximum: 30 minimum: 1 type: integer onTermsRequired: default: skip description: >- O que fazer quando um provider que o agente usaria exige termos de uso de dados que sua equipe ainda não aceitou. Esses providers nunca são chamados. `skip` responde usando providers cujos termos foram aceitos e lista os demais em `exchange.skippedProviders`; `ask` também encerra o turno com uma `pendingApproval` do tipo `terms` e `exchange.requiresAction`. Se omitido em um turno de acompanhamento, o valor do turno anterior é mantido. Consulte [Providers de dados que exigem termos](https://docs.firecrawl.dev/features/agent#data-providers-that-need-terms). enum: - skip - ask type: string requireApproval: default: false description: >- Antes de qualquer chamada paga a um provider, encerre o turno com uma `pendingApproval` do tipo `calls`, que você aprova ou recusa no próximo turno. Exige `mode: "chat"` na mesma solicitação, inclusive em uma solicitação de acompanhamento. type: boolean toolkits: description: >- Selecione até 5 providers pelo slug, por exemplo `["apollo"]`. O agente usará apenas esses providers. Se o campo estiver vazio ou for omitido, todos os providers disponíveis para sua equipe poderão ser usados. items: type: string maxItems: 5 type: array type: object maxCredits: description: >- Máximo de créditos a serem gastos nesta tarefa do agente. O padrão é 2500 se não for definido. Valores acima de 2.500 são sempre cobrados como requisições pagas. type: number mode: default: extract description: >- `extract` retorna o resultado estruturado completo em `data` a cada turno. `chat` permite responder a uma solicitação de acompanhamento que não peça novos dados com uma resposta curta em `message`, em vez de executar novamente. `exchange.requireApproval` exige `chat` na mesma solicitação. Se omitido em um turno de acompanhamento, o modo da conversa é mantido. enum: - extract - chat type: string model: default: spark-2 description: >- Modelo a ser usado na tarefa do agente. spark-2 é o padrão, e todas as execuções são realizadas nele. Os nomes de modelo Spark 1 continuam aceitos para compatibilidade retroativa, mas estão descontinuados e são direcionados para spark-2. enum: - spark-2 - spark-1-mini - spark-1-pro type: string prompt: description: O prompt que descreve quais dados devem ser extraídos maxLength: 10000 type: string schema: description: Esquema JSON opcional para estruturar os dados extraídos type: object strictConstrainToURLs: description: >- Se verdadeiro, o agente visitará somente as URLs fornecidas no array urls type: boolean threadId: description: >- Continue uma conversa existente: passe o `threadId` retornado por uma execução anterior para executar esta solicitação como o próximo turno dessa conversa. As configurações de `urls`, `schema`, `effort`, `mode` e `exchange` omitidas são herdadas do turno anterior. Omita `threadId` para iniciar uma nova conversa. format: uuid type: string threatProtection: $ref: '#/components/schemas/ThreatProtectionOverride' urls: description: Lista opcional de URLs às quais o agente ficará restrito items: format: uri type: string type: array webhook: description: >- Um objeto de especificação de webhook. Inscreve-se em eventos do ciclo de vida do agente (agent.started, agent.action, agent.completed, agent.failed, agent.cancelled). properties: events: default: - started - action - completed - failed - cancelled description: >- Os eventos a enviar para a URL do webhook. Por padrão, todos os eventos. items: enum: - started - action - completed - failed - cancelled type: string type: array headers: additionalProperties: type: string description: Cabeçalhos a enviar para a URL do webhook. type: object metadata: additionalProperties: type: string description: >- Metadados personalizados que serão incluídos em todos os payloads de webhook para este job do agente. type: object url: description: A URL para a qual enviar eventos de webhook. format: uri type: string required: - url type: object required: - prompt type: object required: true responses: '200': content: application/json: schema: properties: id: format: uuid type: string success: type: boolean threadId: description: >- A conversa à qual esta execução pertence. Passe esse valor como `threadId` para continuar a conversa. format: uuid type: string threadTurn: description: >- O turno desta execução na conversa, com numeração a partir de 1. type: integer type: object description: Tarefa do agente iniciada com sucesso '400': content: application/json: schema: properties: error: example: 'Invalid JSON schema: ...' type: string type: object description: >- Solicitação inválida — o corpo da solicitação falhou na validação (por exemplo, um schema JSON inválido). '402': content: application/json: schema: properties: error: example: Payment required to access this resource. type: string type: object description: Pagamento obrigatório '403': content: application/json: schema: properties: error: example: >- This URL (https://example.com) is blocked by your organization's threat protection policy (rule: blocklist). If you believe this is a mistake, contact your organization administrator to adjust the policy (e.g. whitelist the domain). type: string type: object description: >- Proibido — uma URL fornecida está bloqueada pela política de Proteção contra ameaças da equipe. '429': content: application/json: schema: properties: error: example: Rate limit exceeded. type: string type: object description: Muitas solicitações '500': content: application/json: schema: properties: error: example: Failed to passthrough agent request. type: string type: object description: >- Erro interno do servidor — não foi possível acessar o serviço do agente. security: - bearerAuth: [] components: schemas: AuditMetadata: additionalProperties: false description: >- Identificação do usuário incluída nos eventos de log do SIEM quando o SIEM Logging estiver habilitado para a organização. properties: username: description: O nome de usuário associado à requisição. maxLength: 1024 type: string required: - username type: object ThreatProtectionOverride: description: >- Substituição por solicitação da [Proteção contra ameaças](https://docs.firecrawl.dev/features/threat-protection). Os campos fornecidos substituem os campos correspondentes da política da sua organização apenas nesta solicitação; os campos omitidos mantêm os valores definidos no nível da organização. Exige que a Proteção contra ameaças esteja habilitada para sua equipe (recurso enterprise) — caso contrário, a solicitação será rejeitada com 403. Se sua organização tiver desativado substituições por solicitação, qualquer solicitação que inclua este objeto será rejeitada com 403. Se a Proteção contra ameaças for imposta à sua equipe, `mode` não poderá ser definido como `off`. properties: blacklist: description: >- Domínios a serem sempre bloqueados, como domínios simples (`example.com`) ou padrões curinga (`*.example.com`). Sem protocolo, caminho ou porta. items: type: string maxItems: 1000 type: array blockedTlds: description: >- Domínios de nível superior a serem bloqueados diretamente, em minúsculas e sem o ponto inicial (ex.: `zip`). items: type: string maxItems: 1000 type: array failurePolicy: description: >- O que fazer quando o classificador não puder ser acessado: `closed` bloqueia a solicitação, `open` a permite. enum: - open - closed type: string mode: description: >- Modo de verificação de URL para esta solicitação. `normal` verifica as URLs no Google Web Risk (+2 créditos por URL verificada). enum: - 'off' - normal type: string riskScoreThreshold: description: >- Pontuação de risco normalizada (0–100) a partir da qual um veredito do classificador bloqueia a URL. Quanto menor, mais rigoroso. example: 75 maximum: 100 minimum: 0 type: integer whitelist: description: >- Domínios a serem sempre permitidos, como domínios simples ou padrões curinga. Tem prioridade sobre todas as outras regras. items: type: string maxItems: 1000 type: array title: Threat Protection Override type: object securitySchemes: bearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.