CPFHub.io

Agent Skills

Definições de tool/skill prontas para declarar nos seus agentes de IA. Cole diretamente no system prompt ou na configuração de tools do seu framework.

O que é uma Agent Skill?

Uma skill é uma definição estruturada (JSON Schema) que descreve para o LLM quando e como chamar uma função externa. O modelo usa essa definição para decidir quando consultar o CPFHub.io durante a conversa.

Tool: lookup_cpf

Retorna nome, gênero e data de nascimento a partir de um CPF brasileiro. Usa o mesmo nome da tool do MCP Server.

OpenAI / GPT-4 (JSON Schema)

JSON
{
  "type": "function",
  "function": {
    "name": "lookup_cpf",
    "description": "Consulta dados de uma pessoa física brasileira a partir do CPF. Retorna nome completo, gênero e data de nascimento. Use quando o usuário fornecer um CPF e precisar verificar a identidade ou preencher dados cadastrais.",
    "parameters": {
      "type": "object",
      "properties": {
        "cpf": {
          "type": "string",
          "description": "CPF brasileiro com ou sem formatação. Exemplos: '12345678909' ou '123.456.789-09'."
        }
      },
      "required": ["cpf"]
    }
  }
}

Anthropic Claude (tool_use)

JSON
{
  "name": "lookup_cpf",
  "description": "Consulta dados de uma pessoa física brasileira a partir do CPF. Retorna nome completo, gênero e data de nascimento. Use quando o usuário fornecer um CPF e precisar verificar a identidade ou preencher dados cadastrais.",
  "input_schema": {
    "type": "object",
    "properties": {
      "cpf": {
        "type": "string",
        "description": "CPF brasileiro com ou sem formatação. Exemplos: '12345678909' ou '123.456.789-09'."
      }
    },
    "required": ["cpf"]
  }
}

LangChain (Python)

Python
from langchain.tools import tool
import os
import requests

API_KEY = os.environ["CPFHUB_API_KEY"]

@tool
def lookup_cpf(cpf: str) -> dict:
    """
    Consulta dados de uma pessoa física brasileira a partir do CPF.
    Retorna nome completo, gênero e data de nascimento.
    Use quando o usuário fornecer um CPF e precisar verificar identidade.
    
    Args:
        cpf: CPF brasileiro com ou sem formatação (ex: '12345678909')
    """
    r = requests.get(
        f"https://api.cpfhub.io/cpf/{cpf}",
        headers={"x-api-key": API_KEY},
        timeout=10,
    )
    if r.status_code == 404:
        # CPF não encontrado é um resultado normal e não consome crédito
        return {"found": False}
    r.raise_for_status()
    data = r.json()["data"]
    return {
        "found": True,
        "name": data["name"],
        "gender": data["gender"],
        "birthDate": data["birthDate"],
    }

Tool: get_quota_info

Retorna o plano, os créditos restantes e usados e o status de cobrança. Útil para agentes que precisam verificar disponibilidade antes de fazer consultas em lote.

OpenAI / GPT-4

JSON
{
  "type": "function",
  "function": {
    "name": "get_quota_info",
    "description": "Retorna informações sobre os créditos disponíveis e o status do plano CPFHub.io atual. Use antes de iniciar processos em lote para verificar se há créditos suficientes.",
    "parameters": {
      "type": "object",
      "properties": {},
      "required": []
    }
  }
}

Tool: lookup_cpf_realtime

Consulta em Tempo Real na Receita Federal. Exige CPF e data de nascimento e devolve os mesmos campos de POST /cpf/realtime, inclusive deathYear (ano do óbito). O campo sempre vem, como inteiro ou null. Não traz dia nem mês. null aparece quando não há óbito registrado ou quando o valor recebido é inválido. A tool existe no servidor MCP remoto; o pacote local @cpfhub/mcp não a inclui.

Implementação do handler

Independente do framework, o handler que executa a tool é sempre o mesmo:

TypeScript
async function executeTool(name: string, args: Record<string, string>) {
  if (name === 'lookup_cpf') {
    const cpf = args.cpf.replace(/\D/g, '')
    const res = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
      headers: { 'x-api-key': process.env.CPFHUB_API_KEY! },
    })
    const body = await res.json()
    if (!body.success) {
      // Erros de autenticação e conta trazem error como string; os da consulta, error.message
      const message = typeof body.error === 'string' ? body.error : body.error?.message
      return { success: false, status: res.status, error: message }
    }
    return {
      success: true,
      name: body.data.name,
      gender: body.data.gender,
      birthDate: body.data.birthDate,
    }
  }

  if (name === 'get_quota_info') {
    const res = await fetch('https://api.cpfhub.io/quota', {
      headers: { 'x-api-key': process.env.CPFHUB_API_KEY! },
    })
    return res.json() // { success: true, data: { plan, remainingCredits, usedCredits, billingStatus, userId, email } }
  }
}
✦

Dica: instrua o modelo sobre erros

No system prompt, informe o agente o que fazer quando o CPF não for encontrado (HTTP 404, "CPF não encontrado na base de dados"): por exemplo, pedir para o usuário conferir a digitação. Isso evita que o agente fique preso em um loop de retry.

System prompt recomendado

Use este trecho no system prompt do seu agente para maximizar a qualidade das respostas:

Você tem acesso à tool lookup_cpf para validar identidades brasileiras.

Regras:
- Sempre confirme o CPF com o usuário antes de consultar
- Se o CPF não for encontrado, informe que o CPF pode estar incorreto
- Nunca armazene ou repita o CPF completo na conversa; use apenas o nome retornado
- Use o resultado apenas para confirmar identidade, não para outros fins

Atualizado em 3 de outubro de 2026