CPFHub.io
Começar grátis

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
from cpfhub import CPFHub
import os

client = CPFHub(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')
    """
    data = client.lookup(cpf)["data"]
    return {
        "name": data["name"],
        "gender": data["gender"],
        "birthDate": data["birthDate"],
    }

Tool: get_quota_info

Retorna os créditos restantes e status do plano atual. Ú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": []
    }
  }
}

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) {
      // 401/403 trazem error como string; os demais erros, 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, ... } }
  }
}
✦

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 2 de outubro de 2026