Construir un agente
Conecta un agente al servidor MCP de Reclee o arma el tuyo con la API REST y un LLM, con confirmaciones, manejo de next, errores, presupuesto y rate limit.
Hay dos formas de que un agente trabaje en Reclee: conectarlo al servidor MCP, que le da las tools listas para usar, o armar tu propio agente sobre la API REST y el LLM que prefieras. Las dos corren las mismas acciones con el mismo ejecutor, así que las reglas de esta guía valen para ambas.
Opción A: conectar un agente por MCP
Conecta el cliente
El servidor MCP vive en https://app.reclee.com/api/mcp (Streamable HTTP). Un cliente compatible se conecta solo con la URL: descubre la autorización, se registra y abre el navegador para que la persona elija el workspace. Por ejemplo, en Claude Code:
claude mcp add --transport http reclee https://app.reclee.com/api/mcpDespués, /mcp → autenticar. Al aceptar, Reclee crea una API key para esa persona en ese workspace; aparece en Configuración → Developers con el nombre del cliente, y revocarla ahí desconecta al agente. Los detalles y otros clientes están en Conectar un cliente y Autorización.
Quién puede conectar
Solo un miembro con asiento (OWNER o RECRUITER) conecta el MCP. El agente actúa como esa persona, con su rol, en el workspace que eligió. No hay scopes ni token de refresco: el token es una API key que vive hasta que alguien la revoca.
Respeta las confirmaciones
Cada tool trae anotaciones que le dicen al cliente cuánto riesgo tiene:
| Familia | Anotación | Qué debe hacer el agente |
|---|---|---|
READ | readOnlyHint: true | Llamarla libremente. |
DO, CRM | destructiveHint: true | Confirmar con la persona antes de llamar: cambia datos reales. |
PROVIDER | destructiveHint: true | Confirmar y decir qué va a gastar: llama a un proveedor externo y consume uso o créditos. |
GENERATE | destructiveHint: false | Puede llamarla: escribe una propuesta que la persona revisa en Reclee. |
Reclee no muestra una tarjeta de confirmación propia por MCP: confirmar es responsabilidad del cliente. Ver Seguridad y confirmaciones.
Encadena por ids
Cada llamada es independiente: no hay hilo ni sesión. Un objeto se nombra por el id que devolvió una llamada anterior (jobPostId, applicationId, longlistId…). Un buen agente lee primero (list_job_posts, get_job_post, get_application) y recién después escribe con los ids que leyó, nunca con ids inventados.
Ofrece next, no lo ejecutes solo
Una escritura devuelve next: missing dice qué le falta al objeto y suggestions qué tools siguen, con los ids ya resueltos.
{
"next": {
"missing": ["workplaceType"],
"suggestions": [ { "tool": "update_job_post", "input": { "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90" } } ]
}
}El agente tiene que ofrecerle esas tools a la persona, no llamar por su cuenta una que nadie pidió. Una negativa trae missing y suggestions de la misma forma: es la salida para corregir el pedido.
Maneja los errores
Por MCP, una negativa vuelve con isError: true y el JSON { "error": "CODE", "missing"?, "suggestions"? } como texto. Reglas prácticas:
INVALID: los argumentos no pasaron el schema; corrígelos, no reintentes igual.NOT_FOUND: el id no existe en ese workspace; vuelve a leer.- Códigos de estado (
JOB_POST_DRAFT,ALREADY_WRITTEN,STAGE_ONLY_ADVANCES…): explícaselos a la persona y ofrece lassuggestions. 402de uso o créditos (USAGE_EXHAUSTED,NO_CREDITS…): no reintentes; dile qué se agotó.
La lista completa está en Errores y Solución de problemas.
Cuida el presupuesto
Las tools que gastan devuelven cost: aiUsagePct y teamUsagePct como fracción de 0 a 1 del uso del mes que consumió esa llamada, credits los créditos que tomó y billedLater: true cuando una parte se cobra después (una corrida de sourcing, una importación de CVs). Antes de una tool PROVIDER, el agente puede llamar a get_usage para ver dónde está la persona y qué la bloquearía. Ver Créditos y uso.
Respeta el rate limit
Cada persona tiene 60 pedidos por minuto, compartidos entre la API REST y el MCP. Pasado eso, el servidor contesta 429 con el header Retry-After (segundos). Espera ese tiempo antes de reintentar; no reintentes en ráfaga. Ver Rate limits y Límites del MCP.
Opción B: tu propio agente con la API REST y un LLM
Si controlas el loop del agente, usa la API REST: GET /openapi.json (público) trae cada acción en /actions/<tool> con su operationId, su descripción (la misma que lee un modelo por MCP), su familia en x-family y el JSON Schema de su entrada. Con eso armas las tools de tu LLM sin escribirlas a mano.
El ejemplo es agnóstico del proveedor del modelo: callModel es tu función, que recibe los mensajes y las tools y devuelve texto o un pedido de tool. Hace una acción, confirma las que cambian datos, maneja el 429, le devuelve al modelo los errores con sus suggestions y le muestra next para que lo ofrezca.
const API = "https://app.reclee.com/api/v1";
const headers = {
Authorization: `Bearer ${process.env.RECLEE_API_KEY}`,
"Content-Type": "application/json",
};
type Tool = { name: string; description: string; family: string; inputSchema: object };
type ModelTurn =
| { type: "text"; text: string }
| { type: "tool"; name: string; input: Record<string, unknown> };
// Tu adaptador al LLM que uses.
declare function callModel(messages: unknown[], tools: Tool[]): Promise<ModelTurn>;
// Tu forma de preguntarle a la persona (CLI, chat, Slack…).
declare function confirm(question: string): Promise<boolean>;
// 1. Las tools salen del documento OpenAPI.
async function loadTools(): Promise<Tool[]> {
const spec = await fetch(`${API}/openapi.json`).then(r => r.json());
return Object.entries<any>(spec.paths)
.filter(([path]) => path.startsWith("/actions/"))
.map(([, item]) => ({
name: item.post.operationId,
description: item.post.description,
family: item.post["x-family"],
inputSchema: item.post.requestBody.content["application/json"].schema,
}));
}
// 2. Una acción, con reintento ante 429 y la misma Idempotency-Key en cada intento.
async function runAction(tool: string, input: unknown) {
const idempotencyKey = crypto.randomUUID();
for (let attempt = 0; attempt < 3; attempt++) {
const res = await fetch(`${API}/actions/${tool}`, {
method: "POST",
headers: { ...headers, "Idempotency-Key": idempotencyKey },
body: JSON.stringify(input),
});
if (res.status === 429) {
const wait = Number(res.headers.get("Retry-After") ?? 5);
await new Promise(r => setTimeout(r, wait * 1000));
continue;
}
return { ok: res.ok, status: res.status, body: await res.json() };
}
return { ok: false, status: 429, body: { error: "RATE_LIMITED" } };
}
// 3. El loop: el modelo pide una tool, se confirma si cambia datos, el resultado vuelve al modelo.
export async function agent(request: string) {
const tools = await loadTools();
const messages: unknown[] = [{ role: "user", content: request }];
for (let turn = 0; turn < 10; turn++) {
const step = await callModel(messages, tools);
if (step.type === "text") return step.text;
const tool = tools.find(t => t.name === step.name);
if (!tool) {
messages.push({ role: "tool", name: step.name, content: { error: "UNKNOWN_TOOL" } });
continue;
}
if (tool.family !== "GENERATE") {
const ok = await confirm(`¿Ejecuto ${tool.name} con ${JSON.stringify(step.input)}?`);
if (!ok) {
messages.push({ role: "tool", name: tool.name, content: { error: "DECLINED_BY_USER" } });
continue;
}
}
const result = await runAction(tool.name, step.input);
// Éxito: data + next (qué falta y qué sigue). Negativa: error + missing + suggestions.
// En los dos casos el modelo lo recibe tal cual y decide qué ofrecerle a la persona.
messages.push({ role: "tool", name: tool.name, content: result.body });
}
return "Llegué al máximo de pasos.";
}Algunas decisiones del ejemplo, para que las adaptes:
- Las lecturas no están en
/actions/: sonGETsobre recursos (ver Referencia REST). Si tu agente necesita leer, agrega tools propias que llamen a esas rutas; unPOST /actions/<tool>con el nombre de una lectura contesta405 METHOD_NOT_ALLOWED. - Pedir confirmación para todo lo que no es
GENERATEsigue la misma regla que el MCP. Si tu agente corre sin una persona delante, limita la lista de tools a las que de verdad necesita. nextva al modelo, no a unif: el modelo se lo ofrece a la persona en vez de encadenar acciones que nadie pidió.- La misma
Idempotency-Keyen cada reintento hace que un reintento devuelva la primera respuesta en vez de escribir o gastar dos veces. Ver Idempotencia. INVALIDtraedetailscampo por campo: devolvérselo al modelo suele bastar para que corrija los argumentos. Un argumento que el schema no declara también esINVALID(no se descarta), así que pasa los schemas tal cual, con suadditionalProperties: false, para que el modelo no invente campos.