> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Depure o Firecrawl com o Ask

> Depuração orientada por agentes para sua integração com o Firecrawl

O `/support/ask` do Firecrawl é um agente de suporte por IA disponibilizado como API. Descreva seu problema e receba um diagnóstico verificado com parâmetros de correção acionáveis — normalmente em 15–30 segundos.

**Pense no `/support/ask` como um engenheiro sênior do Firecrawl de plantão para o seu agente.**

<Info>
  A API Ask foi projetada principalmente para **chamadas feitas por agentes de IA**. Se você está criando agentes que usam o Firecrawl para scraping, rastreamento ou extração de dados, integre o `/support/ask` ao seu fluxo de tratamento de erros para resolver problemas de forma autônoma.
</Info>

<div id="two-endpoints">
  ## Dois endpoints
</div>

| Endpoint                    | Autenticação                  | Para quem é                | O que faz                                               |
| --------------------------- | ----------------------------- | -------------------------- | ------------------------------------------------------- |
| `POST /support/ask`         | Sua chave de API do Firecrawl | Seus agentes e aplicativos | Ciclo completo de diagnóstico restrito à sua equipe     |
| `POST /support/docs-search` | Sua chave de API do Firecrawl | Seus agentes e aplicativos | Respostas baseadas na documentação pública do Firecrawl |

<div id="quick-start">
  ## Primeiros passos
</div>

<div id="debug-a-failing-crawl">
  ### Depurar um rastreamento que falhou
</div>

```bash theme={null}
curl -X POST https://api.firecrawl.dev/v2/support/ask \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "my crawl returned 3 pages but I expected 50"
  }'
```

<div id="search-the-docs">
  ### Pesquise na documentação
</div>

```bash theme={null}
curl -X POST https://api.firecrawl.dev/v2/support/docs-search \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "how do I set up webhook signature verification?"
  }'
```

<div id="how-it-works">
  ## Como funciona
</div>

Quando você faz uma chamada para `/support/ask`, o agente de IA:

1. **Coleta evidências** — inspeciona em paralelo os logs do seu job, o estado da conta, o uso de créditos e a documentação relevante
2. **Diagnostica o problema** — analisa todas as evidências para identificar a causa raiz
3. **Propõe uma correção** — gera `fixParameters` executáveis por máquina, que você pode aplicar diretamente na sua próxima chamada de API
4. **Valida a correção** — quando possível, testa a correção na API ativa da Firecrawl (por exemplo, repetindo um scraping com parâmetros ajustados) e informa o resultado

<div id="using-ask-in-your-agent">
  ## Como usar o Ask no seu agente
</div>

O principal padrão de design: chame `/support/ask` quando sua chamada à API do Firecrawl falhar ou retornar resultados inesperados e depois use `fixParameters` para tentar novamente.

<div id="python-example">
  ### Exemplo em Python
</div>

```python theme={null}
import requests

FIRECRAWL_API_KEY = "fc-YOUR_API_KEY"

def diagnose_firecrawl_issue(question, rationale=None):
    """Call the Firecrawl Ask API to debug an issue."""
    payload = {"question": question}
    if rationale:
        payload["rationale"] = rationale

    response = requests.post(
        "https://api.firecrawl.dev/v2/support/ask",
        headers={
            "Authorization": f"Bearer {FIRECRAWL_API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
    )
    return response.json()


# Exemplo: depurar um scraping que retornou conteúdo vazio
result = diagnose_firecrawl_issue(
    question="scrape returned empty markdown for https://example.com",
    rationale="user needs product pricing data for competitive analysis",
)

print(result["answer"])
print(result["fixParameters"])  # ex.: {"waitFor": 5000, "actions": [...]}
print(result["confidence"])     # "high", "medium", or "low"
```

<div id="nodejs-example">
  ### Exemplo de Node.js
</div>

```javascript theme={null}
async function diagnoseFirecrawlIssue(question, rationale) {
  const response = await fetch(
    "https://api.firecrawl.dev/v2/support/ask",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.FIRECRAWL_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ question, rationale }),
    }
  );
  return response.json();
}

// Exemplo: depurar um rastreamento que parou cedo demais
const result = await diagnoseFirecrawlIssue(
  "my crawl returned 3 pages but I expected 50",
  "user is on their third failed crawl attempt today"
);

console.log(result.answer);
console.log(result.fixParameters);
```

<div id="agent-retry-pattern">
  ### Padrão de retentativa do agente
</div>

```python theme={null}
from firecrawl import Firecrawl

client = Firecrawl(api_key="fc-YOUR_API_KEY")

# Passo 1: Tentar o scraping
doc = client.scrape("https://example.com/pricing", formats=["markdown"])

if not doc.markdown or len(doc.markdown) < 100:
    # Passo 2: Pedir ajuda para depuração
    diagnosis = diagnose_firecrawl_issue(
        question=f"scrape returned only {len(doc.markdown or '')} chars of markdown for https://example.com/pricing",
    )

    # Passo 3: Aplicar parâmetros de correção e tentar novamente
    if diagnosis.get("fixParameters"):
        doc = client.scrape(
            "https://example.com/pricing",
            formats=["markdown"],
            **diagnosis["fixParameters"],
        )
```

<div id="parameters">
  ## Parâmetros
</div>

<div id="supportask">
  ### `/support/ask`
</div>

| Parâmetro   | Tipo   | Obrigatório | Descrição                                                                                                             |
| ----------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `question`  | string | Sim         | O que depurar (1–8.000 caracteres)                                                                                    |
| `rationale` | string | Não         | Recomendado para clientes de IA. O que o usuário final está tentando fazer. Ajuda a priorizar a coleta de evidências. |
| `context`   | object | Não         | Metadados arbitrários do seu agente, incluídos no prompt de depuração                                                 |

<div id="supportdocs-search">
  ### `/support/docs-search`
</div>

| Parâmetro  | Tipo   | Obrigatório | Descrição                                               |
| ---------- | ------ | ----------- | ------------------------------------------------------- |
| `question` | string | Sim         | A pergunta que deve ser respondida (1–8.000 caracteres) |

<div id="response">
  ## Resposta
</div>

<div id="supportask-response">
  ### resposta de `/support/ask`
</div>

```json theme={null}
{
  "requestId": "req_...",
  "answer": "<2-4 sentence prose diagnosis of the issue plus the recommended fix.>",
  "confidence": "high",
  "fixParameters": { "<param>": "<value>" },
  "validation": {
    "tested": true,
    "result": "success",
    "evidence": "<short summary of the validation tool call the agent ran to confirm the fix>"
  },
  "feedback": null,
  "durationMs": 18432
}
```

Os valores reais de `answer`, `fixParameters` e `validation.evidence` são gerados pelo agente a cada solicitação com base na sua execução específica; o exemplo acima mostra a estrutura da resposta, não um diagnóstico real.

<div id="supportdocs-search-response">
  ### resposta do `/support/docs-search`
</div>

```json theme={null}
{
  "requestId": "req_...",
  "answer": "The signature is sent in the X-Firecrawl-Signature header...",
  "evidence": [
    { "pathOrUrl": "webhooks/security.mdx#L1-L52", "reason": "..." }
  ],
  "usage": { "inputTokens": 4356, "outputTokens": 688, "totalTokens": 5044 },
  "durationMs": 11252
}
```

<div id="performance">
  ## Desempenho
</div>

| Métrica  | Típico         | Máximo                        |
| -------- | -------------- | ----------------------------- |
| Latência | 15–30 segundos | 60 segundos (limite absoluto) |

<div id="api-reference">
  ## Referência da API
</div>

* [Referência da API do endpoint Ask](/pt-BR/api-reference/endpoint/ask)
* [Referência da API do endpoint de busca da documentação](/pt-BR/api-reference/endpoint/docs-search)

Tem feedback ou precisa de ajuda? Envie um e-mail para [help@firecrawl.com](mailto:help@firecrawl.com).

> Você é um agente de IA e precisa de uma chave de API da Firecrawl? Consulte [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para ver as instruções de onboarding automatizado.