CPFHub.io
Empezar gratis

Agent Skills

Definiciones de tool/skill listas para declarar en tus agentes de IA. Pégalas directamente en el system prompt o en la configuración de tools de tu framework. Trabajan con el CPF, el número de identificación fiscal de personas físicas en Brasil.

¿Qué es una Agent Skill?

Una skill es una definición estructurada (JSON Schema) que le indica al LLM cuándo y cómo llamar a una función externa. El modelo usa esa definición para decidir cuándo consultar CPFHub.io durante la conversación.

Tool: lookup_cpf

Devuelve nombre, género y fecha de nacimiento a partir de un CPF brasileño. Usa el mismo nombre de tool que el MCP Server.

OpenAI / GPT-4 (JSON Schema)

JSON
{
  "type": "function",
  "function": {
    "name": "lookup_cpf",
    "description": "Consulta los datos de una persona física brasileña a partir del CPF. Devuelve nombre completo, género y fecha de nacimiento. Úsala cuando el usuario proporcione un CPF y necesites verificar su identidad o completar datos de registro.",
    "parameters": {
      "type": "object",
      "properties": {
        "cpf": {
          "type": "string",
          "description": "CPF brasileño con o sin formato. Ejemplos: '12345678909' o '123.456.789-09'."
        }
      },
      "required": ["cpf"]
    }
  }
}

Anthropic Claude (tool_use)

JSON
{
  "name": "lookup_cpf",
  "description": "Consulta los datos de una persona física brasileña a partir del CPF. Devuelve nombre completo, género y fecha de nacimiento. Úsala cuando el usuario proporcione un CPF y necesites verificar su identidad o completar datos de registro.",
  "input_schema": {
    "type": "object",
    "properties": {
      "cpf": {
        "type": "string",
        "description": "CPF brasileño con o sin formato. Ejemplos: '12345678909' o '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 los datos de una persona física brasileña a partir del CPF.
    Devuelve nombre completo, género y fecha de nacimiento.
    Úsala cuando el usuario proporcione un CPF y necesites verificar su identidad.
    
    Args:
        cpf: CPF brasileño con o sin formato (ej: '12345678909')
    """
    r = requests.get(
        f"https://api.cpfhub.io/cpf/{cpf}",
        headers={"x-api-key": API_KEY},
        timeout=10,
    )
    if r.status_code == 404:
        # Un CPF no encontrado es un resultado normal y no consume 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

Devuelve el plan, los créditos restantes y usados y el estado de facturación. Útil para agentes que necesitan verificar la disponibilidad antes de hacer consultas por lote.

OpenAI / GPT-4

JSON
{
  "type": "function",
  "function": {
    "name": "get_quota_info",
    "description": "Devuelve información sobre los créditos disponibles y el estado del plan actual de CPFHub.io. Úsala antes de iniciar procesos por lote para verificar si hay créditos suficientes.",
    "parameters": {
      "type": "object",
      "properties": {},
      "required": []
    }
  }
}

Tool: lookup_cpf_realtime

Consulta en Tiempo Real en la Receita Federal (la autoridad tributaria federal de Brasil). Exige el CPF y la fecha de nacimiento y devuelve los mismos campos de POST /cpf/realtime, incluido deathYear (año de fallecimiento). El campo siempre viene, como entero o null. No trae día ni mes. null aparece cuando no hay fallecimiento registrado o cuando el valor recibido es inválido. La tool existe en el servidor MCP remoto. El paquete local @cpfhub/mcp no la incluye.

Implementación del handler

Sin importar el framework, el handler que ejecuta la tool es siempre el mismo:

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) {
      // Los errores de autenticación y de cuenta traen error como string, los de la 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 } }
  }
}
✦

Consejo: indica al modelo cómo manejar los errores

En el system prompt, dile al agente qué hacer cuando el CPF no se encuentra (HTTP 404, "CPF não encontrado na base de dados", que significa "CPF no encontrado en la base de datos"): por ejemplo, pedir al usuario que revise lo que escribió. Así evitas que el agente quede atrapado en un bucle de reintentos.

System prompt recomendado

Usa este fragmento en el system prompt de tu agente para maximizar la calidad de las respuestas:

Tienes acceso a la tool lookup_cpf para validar identidades brasileñas.

Reglas:
- Confirma siempre el CPF con el usuario antes de consultarlo
- Si el CPF no se encuentra, informa que el CPF puede estar incorrecto
- Nunca almacenes ni repitas el CPF completo en la conversación. Usa solo el nombre devuelto
- Usa el resultado solo para confirmar la identidad, no para otros fines

Actualizado el 3 de octubre de 2026