Agent Skills
现成的工具/技能定义，可直接在您的 AI 智能体中声明。将它们粘贴到系统提示词或框架的工具配置中即可。这些定义处理的是 CPF（巴西个人税号）。
什么是 Agent Skill？
Skill 是一种结构化定义（JSON Schema），用来告诉 LLM 何时以及如何调用外部函数。模型根据该定义判断在对话中何时查询 CPFHub.io。
工具：lookup_cpf
根据巴西 CPF 返回姓名、性别和出生日期。工具名称与 MCP Server 中的一致。
OpenAI / GPT-4（JSON Schema）
JSON
{
"type": "function",
"function": {
"name": "lookup_cpf",
"description": "Looks up data for a Brazilian individual from their CPF. Returns full name, gender and date of birth. Use when the user provides a CPF and you need to verify identity or fill in registration data.",
"parameters": {
"type": "object",
"properties": {
"cpf": {
"type": "string",
"description": "Brazilian CPF with or without formatting. Examples: '12345678909' or '123.456.789-09'."
}
},
"required": ["cpf"]
}
}
}Anthropic Claude（tool_use）
JSON
{
"name": "lookup_cpf",
"description": "Looks up data for a Brazilian individual from their CPF. Returns full name, gender and date of birth. Use when the user provides a CPF and you need to verify identity or fill in registration data.",
"input_schema": {
"type": "object",
"properties": {
"cpf": {
"type": "string",
"description": "Brazilian CPF with or without formatting. Examples: '12345678909' or '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:
"""
Looks up data for a Brazilian individual from their CPF.
Returns full name, gender and date of birth.
Use when the user provides a CPF and you need to verify identity.
Args:
cpf: Brazilian CPF with or without formatting (e.g. '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 not found is a normal result and does not use a credit
return {"found": False}
r.raise_for_status()
data = r.json()["data"]
return {
"found": True,
"name": data["name"],
"gender": data["gender"],
"birthDate": data["birthDate"],
}工具：get_quota_info
返回套餐、剩余和已用积分以及计费状态。适用于在执行批量查询前需要确认可用额度的智能体。
OpenAI / GPT-4
JSON
{
"type": "function",
"function": {
"name": "get_quota_info",
"description": "Returns information about the available credits and the status of the current CPFHub.io plan. Use before starting batch processes to check whether there are enough credits.",
"parameters": {
"type": "object",
"properties": {},
"required": []
}
}
}工具：lookup_cpf_realtime
向 Receita Federal（巴西联邦税务局）发起的实时查询。需要提供 CPF 和出生日期，返回与 POST /cpf/realtime 相同的字段，包括 deathYear（死亡年份）。该字段始终存在，为整数或 null，不包含日和月。没有死亡记录或收到的值无效时为 null。该工具仅在远程 MCP 服务器上提供。本地 @cpfhub/mcp 包不包含此工具。
Handler 实现
无论使用哪个框架，执行工具的 handler 都是一样的：
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) {
// Authentication and account errors come with error as a string; lookup errors, 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 } }
}
}✦
提示：告诉模型如何处理错误
请在系统提示词中告诉智能体，未查到 CPF 时（HTTP 404，"CPF não encontrado na base de dados"，意思是“数据库中未找到该 CPF”）应该怎么做，例如请用户检查输入。这样可以避免智能体陷入重试循环。
推荐的系统提示词
在智能体的系统提示词中加入以下片段，可以提升回答质量：
你可以使用 lookup_cpf 工具验证巴西用户身份。
规则：
- 查询前始终先与用户确认 CPF
- 如果未查到 CPF，告知用户 CPF 可能有误
- 不要在对话中存储或重复完整的 CPF。仅使用返回的姓名
- 查询结果只用于确认身份，不得用于其他目的更新于 2026 年 10 月 3 日