Dónde entra la API del cliente

Como un nodo R nuevo del grafo, autorizado paso a paso por el plano de herramientas, nunca como clave global.

verificado en main f41235c7
y en la API de producción
23-oct-2026
Diagrama del recorrido de la API del cliente en AgentSquad
llamada a la API respuesta activo en producción construido, uso en producción sin verificar construido, sin encender por construir lo pone el cliente

Cómo leer el diagrama

Elige una pieza del diagrama para ver qué hace, dónde vive en el código y en qué estado está hoy. También puedes pulsar Recorrer paso a paso.

Simulador del PDP

Mismo orden de decisión que tool-broker/default-authorize.ts y pdp.ts.

Si algo falla dentro del PDP, niega con reason="error": nunca deja pasar por defecto.

Nuestras cuentas frente a la API del cliente

Tornado, DataForSEO, ScrapeCreators y Apify entran con una clave global del servidor. Sirve porque las cuentas son nuestras. Con una cuenta del cliente, esa misma forma dejaría su credencial al alcance de cualquier workspace.

Nuestras cuentas (hoy)API del cliente (propuesta)
Dueño de la cuentaAgentSquadEl cliente
Dónde vive la credencialClave global en el .env del servidor, la operación la lee directoFuera de la operación: en el Gateway de AgentCore, o por construir si usamos el MCP propio
Quién puede usarlaCualquier corrida de cualquier workspaceSolo los pasos del workspace que tiene la conexión
Autorización por pasoNo hayPDP y permiso firmado: este paso, una herramienta, 5 minutos
Aprobación humanaNoOpcional por operación (approval_required)
Cupos contra ráfagasprovider-slots.tsSe reutiliza provider-slots.ts
CostoReserva de presupuesto de investigaciónSe reutiliza si la API cobra por llamada
Dónde queda la respuestawork_items y la evidencia de investigaciónwork_items del workspace, aislado por RLS

Qué falta para encenderlo

El plano de herramientas está construido, pero en producción está apagado. Esto es lo que encontré hoy en el código y en el proceso vivo de la API.

  1. faltaSecreto de firma. TOOL_BROKER_GRANT_SECRET no está en la API de producción. Sin él, cualquier operación con tool_binding falla antes de decidir.
  2. faltaAdaptador. Producción no define TOOL_PLANE_ADAPTER, así que usa el MCP propio, que arranca sin herramientas. Hay que registrar la del cliente o configurar AgentCore Gateway.
  3. sin verificarCredencial. La conexión tiene un campo credential_ref, pero ningún código lo lee. En AgentCore, el token sale de Secrets Manager al aprovisionar el Gateway; no comprobé acceso a AWS desde producción. Con el MCP propio, está por construir.
  4. por construirLa operación nueva. Entrada en el catálogo con su firma, schemas Zod de entrada y salida, side_effects: 'tool' y su tool_binding.
  5. por construirLa conexión del workspace. Una fila habilitada en tool_bindings: una por workspace y capacidad.
  6. por construirProcedencia en el informe. Hoy cubre videos, posts y transcripts. Una fuente nueva necesita su lugar para que el informe la cite.
  7. por probarUna corrida real de punta a punta. Demo, GitHub y Slack ya declaran tool_binding; sin el secreto, hoy ninguna puede pasar el control.

¿Consulta en vivo o carga a la biblioteca?

El control de acceso es el mismo en los dos casos. Cambia cuándo se llama a la API: en cada encargo, o solo al cargar.

Consulta en vivo

  • Los datos cambian seguido.
  • Son demasiados para copiarlos.
  • El contrato no permite guardar una copia.
  • Cada encargo pregunta algo distinto.

El nodo R llama a la API dentro del encargo.

Carga a la biblioteca

  • El conjunto es estable.
  • Se consulta muchas veces.
  • Conviene buscar por significado, con traza de cada consulta.
  • Trae datos personales que conviene anonimizar antes de que entren al grafo.

Una operación de carga llama a la API; el encargo lee la biblioteca con document.query.

Ojo: document.ingest no sirve para cargarla. Solo acepta URLs públicas sin autenticación (tiene una guarda anti SSRF). La carga necesita su propia operación con tool_binding.

Para decidir necesito del cliente: qué datos trae, cada cuánto cambian, cómo se autentica, qué límites de uso tiene y si incluye datos personales.