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: get_person_by_cpf

Retorna nome, gênero e data de nascimento a partir de um CPF brasileiro.

OpenAI / GPT-4 (JSON Schema)

JSON
{
  "type": "function",
  "function": {
    "name": "get_person_by_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": "get_person_by_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 get_person_by_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')
    """
    result = client.lookup(cpf)
    return {
        "name": result.data.name,
        "gender": result.data.gender,
        "birth_date": result.data.birth_date,
    }

Tool: get_quota_information

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_information",
    "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
import { CPFHub, CPFHubError } from '@cpfhub/sdk'

const client = new CPFHub({ apiKey: process.env.CPFHUB_API_KEY })

async function executeTool(name: string, args: Record<string, string>) {
  if (name === 'get_person_by_cpf') {
    try {
      const result = await client.lookup(args.cpf)
      return {
        success: true,
        name: result.data.name,
        gender: result.data.gender,
        birthDate: result.data.birthDate,
      }
    } catch (err) {
      if (err instanceof CPFHubError) {
        return { success: false, error: err.code, message: err.message }
      }
      throw err
    }
  }
}
✦

Dica: instrua o modelo sobre erros

No system prompt, informe o agente o que fazer quando o CPF não for encontrado (CPF_NOT_FOUND) - 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 get_person_by_cpf para validar identidades brasileiras.

Regras:
- Sempre confirme o CPF com o usuário antes de consultar
- Se o CPF não for encontrado (CPF_NOT_FOUND), 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 12 de maio de 2026