Reclee

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/mcp

Despué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:

FamiliaAnotaciónQué debe hacer el agente
READreadOnlyHint: trueLlamarla libremente.
DO, CRMdestructiveHint: trueConfirmar con la persona antes de llamar: cambia datos reales.
PROVIDERdestructiveHint: trueConfirmar y decir qué va a gastar: llama a un proveedor externo y consume uso o créditos.
GENERATEdestructiveHint: falsePuede 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 las suggestions.
  • 402 de 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/: son GET sobre recursos (ver Referencia REST). Si tu agente necesita leer, agrega tools propias que llamen a esas rutas; un POST /actions/<tool> con el nombre de una lectura contesta 405 METHOD_NOT_ALLOWED.
  • Pedir confirmación para todo lo que no es GENERATE sigue 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.
  • next va al modelo, no a un if: el modelo se lo ofrece a la persona en vez de encadenar acciones que nadie pidió.
  • La misma Idempotency-Key en cada reintento hace que un reintento devuelva la primera respuesta en vez de escribir o gastar dos veces. Ver Idempotencia.
  • INVALID trae details campo por campo: devolvérselo al modelo suele bastar para que corrija los argumentos. Un argumento que el schema no declara también es INVALID (no se descarta), así que pasa los schemas tal cual, con su additionalProperties: false, para que el modelo no invente campos.

Siguientes pasos

En esta página