# AgentSafePath — índice agent-first de empresas reais do Brasil

> Dados de empresas do Brasil de forma estruturada, verificável e com proveniência,
> para agentes de IA agirem com segurança. Beta FECHADA: busca e perfil exigem chave
> (X-Agent-ID + X-Agent-API-Key). Nada de dados inventados; cada afirmação tem fonte.

## Base
- Site (descoberta/onboarding): https://agentsafepath.com
- API: https://api.agentrank.intelligenceofcode.com
- Docs para agentes (máquina): https://api.agentrank.intelligenceofcode.com/api/agent/docs
- Manifesto público: https://agentsafepath.com/agentrank.json

## Acesso (beta fechada)
- Os endpoints agentivos exigem autenticação por chave.
- Headers: `X-Agent-ID: <seu_agent_id>` e `X-Agent-API-Key: <sua_chave>`
  (ou `Authorization: Bearer <sua_chave>`).
- Solicite acesso: e-mail saviodamato@gmail.com (descreva o agente e o uso).
- A API pública sem chave NÃO responde à busca (por design, acesso identificado).

## Endpoints agentivos (exigem chave)
- POST /api/agent/search — busca por intenção em linguagem natural.
- GET  /api/agents/company/{id}.json — perfil agent-first com proveniência.
- POST /api/agent/feedback — feedback do agente sobre um resultado (usa query_id).

## Consulta
POST /api/agent/search
Headers: X-Agent-ID, X-Agent-API-Key
{ "intent": "restaurante em Pinheiros com WhatsApp", "limit": 5 }

Resposta:
- query_id: identificador da consulta (use no feedback).
- recommendations[]: name, category, region, trust_score, match_reasons, sources.
- parsed_query: como a intenção foi interpretada (city, category, required_contact_types).
- warnings[]: lacunas (ex.: sem resultado acionável).

## Feedback
POST /api/agent/feedback
{ "query_id": "q_...", "result_id": 123, "outcome": "useful", "action_taken": "clicked_whatsapp" }
- outcome: useful | not_useful | wrong_category | no_contact | stale_data | no_result | other
- action_taken: clicked_phone | clicked_whatsapp | clicked_website | requested_company_profile | none | other

## Interpretação
- provenance/confidence: cada afirmação traz origem (declared/inferred/observed) e grau de
  sustentação por evidência — não é garantia de verdade.
- trust_score (0–100): confiabilidade para se comprometer.
- Fontes públicas licenciadas (ex.: Cadastur/Min. Turismo, CNPJ/Receita Federal).

## Privacidade
- Não enviar dados pessoais do usuário final (CPF, telefone/e-mail pessoal, dados
  financeiros, tokens de terceiros, conversas privadas).