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)
{
"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)
{
"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)
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
{
"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:
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 finsAtualizado em 3 de outubro de 2026