@getsupervisor/agents-studio-sdk 1.18.0 → 1.20.0

package/CHANGELOG.md

@@ -1,3 +1,71 @@
+## v1.19.0
+
+## [1.19.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.18.0...v1.19.0) (2025-10-30)
+
+### Features
+
+* add AgentMutationRequestTemplate and update MCP documentation ([9c8ac53](https://github.com/julio-supervisor/agents-studio-be/commit/9c8ac53110c43c173afbbfab9c36e1671612d37a))
+* add api-query-builder dependency and update related migrations for JSONB support ([8558541](https://github.com/julio-supervisor/agents-studio-be/commit/855854145208f6695630ef583a830c019987f653))
+* add geocoding tool integration with Google Maps API ([08c7f4a](https://github.com/julio-supervisor/agents-studio-be/commit/08c7f4a2047aef4af658f4c34210b8e1189231e5))
+* add MCP documentation for prompts, resource templates, resources, tools, and server examples ([dda0d61](https://github.com/julio-supervisor/agents-studio-be/commit/dda0d617fb5abfc4f9b6076413dc984b7d98346f))
+* add test for fallback to AnonymousToolResolver when token lacks name ([ca3f65a](https://github.com/julio-supervisor/agents-studio-be/commit/ca3f65a6b8bae70ec1f5f2a0e094b08f33d6e2e2))
+* add tests for Tool entities metadata and relationships in TypeORM ([f07d862](https://github.com/julio-supervisor/agents-studio-be/commit/f07d86291625710d839d032d2998b5c6ba034827))
+* add tool schema validation and configuration management ([4f49a6b](https://github.com/julio-supervisor/agents-studio-be/commit/4f49a6b3d5fe09b9f525449e80cd7cc49bd5bf99))
+* add unit tests for event subscription and webhook DTOs with validation checks ([4f65c83](https://github.com/julio-supervisor/agents-studio-be/commit/4f65c836cb04020ba7e4725a79127949166f119f))
+* add unit tests for ExecutionToolRegistry and ToolExecutionUnsupportedException ([32b0e92](https://github.com/julio-supervisor/agents-studio-be/commit/32b0e92f789841defb88db8f97cdb56c3d1fb69d))
+* add unit tests for voice call execution and processing tools ([976d762](https://github.com/julio-supervisor/agents-studio-be/commit/976d76217852a08dbf3ae5e0d1a321926e952618))
+* add unit tests for WorkspaceEnablementService to validate provider readiness and error handling ([b84785d](https://github.com/julio-supervisor/agents-studio-be/commit/b84785d0bc7acfabfb302e8ba25df18fa3f9b6ee))
+* add VoiceCallExecutionTemplate for executing voice calls with metadata and notes ([14105dc](https://github.com/julio-supervisor/agents-studio-be/commit/14105dc84cd38b963f3fbf63d5fa16bc0a590f80))
+* enhance filter and search handling in CatalogItemsListTool ([da00a76](https://github.com/julio-supervisor/agents-studio-be/commit/da00a76ac96e7d2e3ca6e66e14a1071bc073fa49))
+* enhance tag suggestion logic for agent creation based on channel and description ([87c4eff](https://github.com/julio-supervisor/agents-studio-be/commit/87c4eff14a23f6c2931a8582316b1f00a7979620))
+* enhance Voice Retell integration with new subscriber and improved error handling ([ad45795](https://github.com/julio-supervisor/agents-studio-be/commit/ad45795eb46b7ecb692b950077275a3bbb0b76ef))
+* implement AgentBlueprintMutatedEvent for agent blueprint updates and sync ([20c6fef](https://github.com/julio-supervisor/agents-studio-be/commit/20c6fef78329211d9ce7676c8dbcc1e98c0367cb))
+* Implement catalog management tools and resources ([b12ba91](https://github.com/julio-supervisor/agents-studio-be/commit/b12ba9126c3aa060ae83c7df5f1e92c1dd55fa79))
+* implement tool connection and execution API with idempotency support ([af236be](https://github.com/julio-supervisor/agents-studio-be/commit/af236be4163a784d7ee4b2e805cfc7c0db89b5bd))
+* implement tool event logging in ToolConnectionService ([260c46c](https://github.com/julio-supervisor/agents-studio-be/commit/260c46ceeee0b867a32897c23a336ec46d18a747))
+* implement voice call execution tool with Redis queue for concurrency handling ([24716e0](https://github.com/julio-supervisor/agents-studio-be/commit/24716e029f4554cc51d7a1dc1c347b8974b0d0b9))
+* integrate CqrsModule and update Retell API base URL to v1 for consistency ([c1647d5](https://github.com/julio-supervisor/agents-studio-be/commit/c1647d59a9e77178d04b0a434155073f523d215c))
+* **mcp:** implement agent blueprints and versions tools ([0026a1a](https://github.com/julio-supervisor/agents-studio-be/commit/0026a1ac9cbfe6a7f0d14faeaaedcc971fa02093))
+* **migration:** add notes column to agent_versions and remove description column ([ffb9960](https://github.com/julio-supervisor/agents-studio-be/commit/ffb9960b6ce6171918ea7e06a5b2f3b6b93a79ff))
+* **migration:** add versioning and metadata columns to agent_versions table ([9cb9321](https://github.com/julio-supervisor/agents-studio-be/commit/9cb932174cd4be43feebc6dca5db555aedcbc16b))
+* **migration:** remove deleted_at from SeedWebhookEventsCatalog migration ([add2b6e](https://github.com/julio-supervisor/agents-studio-be/commit/add2b6ea3b12edc0c59e55144eb5f0134332d3c8))
+* **migration:** simplify notes column addition and remove description column logic ([1d2afa9](https://github.com/julio-supervisor/agents-studio-be/commit/1d2afa9ad13bb75086b1f9b996236852174192ba))
+* **migration:** update unique index creation for catalog_items to remove condition on deleted_at ([89be707](https://github.com/julio-supervisor/agents-studio-be/commit/89be70751ef1df0f852de2ed98ee4e5b177ac13a))
+* refactor error handling in VoiceRetellResolver with adapter transformers ([72f5536](https://github.com/julio-supervisor/agents-studio-be/commit/72f55361cff8db3fa83e994799ffb1452d108ef7))
+* refactor ToolLookupService and related repositories for enhanced functionality ([5132c21](https://github.com/julio-supervisor/agents-studio-be/commit/5132c21aff246d22d44f6ae6a6c74341de29264d))
+* **tests:** add unit tests for tools service and related mappers ([474e56b](https://github.com/julio-supervisor/agents-studio-be/commit/474e56be28bb77c26203a777e09c6758314a0017))
+* update prompts to clarify catalog selection limitations and read-only status ([50eb953](https://github.com/julio-supervisor/agents-studio-be/commit/50eb953ddc6e6c581025c01a49f12c29ec2a01f8))
+* update RetellAdapter to handle versioned base URLs for phone call creation ([bab716f](https://github.com/julio-supervisor/agents-studio-be/commit/bab716f86f68de08d4cee0d28213ee33ee4e8207))
+* update RetellAdapter to use new parameter names and API path for phone call creation ([c93df0e](https://github.com/julio-supervisor/agents-studio-be/commit/c93df0ebc272c6e805a9542b4922701a0cfbaf5b))
+* update voice call execution flow and configuration ([9c67be6](https://github.com/julio-supervisor/agents-studio-be/commit/9c67be61b3dfcb7df4268ab51215c8b0d5a33978))
+* **workspaces:** implement workspace settings repository and specifications ([e720f8e](https://github.com/julio-supervisor/agents-studio-be/commit/e720f8e4c9d504b634728db27207b1ab958dc382))
+
+### Bug Fixes
+
+* update Redis queue naming from 'voice-calls:execute' to 'voice-calls-execute' for consistency ([264ec23](https://github.com/julio-supervisor/agents-studio-be/commit/264ec2320a423471829c94c588cc5a9b2a0a63af))
+
+
+## v1.18.0
+
+## [1.18.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.17.0...v1.18.0) (2025-10-23)
+
+### Features
+
+* add webhooks management API ([bb1a1fb](https://github.com/julio-supervisor/agents-studio-be/commit/bb1a1fb17f48a7a52e82c07d12d32f57240c8604))
+* **docs:** add webhook terminology and definitions for agent association and URL reuse ([82985e8](https://github.com/julio-supervisor/agents-studio-be/commit/82985e8bbbc7e7cd2d0e15f0e77e0adc859d01a2))
+* **openapi:** enhance webhook descriptions with optional agent association and URL reuse details ([fc9b2d9](https://github.com/julio-supervisor/agents-studio-be/commit/fc9b2d9099116541d841548adf935f9c0f4a0c99))
+* **tests:** add WebhookEventKey setup and teardown for EventSubscriptionTypeormRepository tests ([b7c28c5](https://github.com/julio-supervisor/agents-studio-be/commit/b7c28c51bc86cf4bc08d83e511429a9cb8fab066))
+* **tests:** enhance WebhookEventKey setup and teardown in event subscription tests ([b717c89](https://github.com/julio-supervisor/agents-studio-be/commit/b717c8916c0147b467044387d9e73988454cf74f))
+* **webhooks:** add agent association to webhooks ([d2d5eb1](https://github.com/julio-supervisor/agents-studio-be/commit/d2d5eb175dc5c43c405a93f961ca70f2426f8d3f))
+* **webhooks:** add webhook event catalog and related migrations ([91ceec2](https://github.com/julio-supervisor/agents-studio-be/commit/91ceec203706bc79ce775063f9a9a9ba9eb698ca))
+* **webhooks:** implement event subscription and webhook entities, specifications, and factories ([7ba841e](https://github.com/julio-supervisor/agents-studio-be/commit/7ba841e21697ab2f38dedd8b5243091e250cff98))
+
+### Bug Fixes
+
+* update EventSubscription references to use EventSubscriptionDetail ([a1ff2f6](https://github.com/julio-supervisor/agents-studio-be/commit/a1ff2f611748783c87dfe43c8597de0a2ee89ae4))
+* update reference in EventSubscriptionListResponse from EventSubscriptionSummary to EventSubscriptionDetail ([9bc602f](https://github.com/julio-supervisor/agents-studio-be/commit/9bc602f14b36612ba993888e9c0354f6431b824e))
+
+
 ## v1.17.0
 
 ## [1.17.0](https://github.com/julio-supervisor/agents-studio-be/compare/v1.16.0...v1.17.0) (2025-10-22)

package/README.md

@@ -239,6 +239,43 @@ API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... \
 npx tsx examples/agents-crud.ts
 ```
 
+## Tools y conexiones
+
+Namespace: `client.tools`
+
+- `tools.list(options?)` — catálogo paginado de tools con filtros por tipo de agente.
+- `tools.listResources(toolId, options?)` — recursos cargados (docs, media, archivos).
+- `tools.uploadResource(toolId, payload)` — carga o actualiza recursos usando `FormData`.
+- `tools.execute(toolId, payload, { idempotencyKey? })` — ejecuta una acción declarada en la tool.
+- `tools.connect(toolId, payload, { idempotencyKey? })` — crea una conexión entre un agente y la tool.
+
+Ejemplo de conexión a `voice.calls` y lectura de las guías de uso:
+
+```ts
+const connection = await client.tools.connect('voice.calls', {
+  agentId: agent.agentId,
+  workspaceId: client.workspace.get(),
+  metadata: {
+    // Configuración adicional que quieras adjuntar a la conexión
+  },
+});
+
+console.log(connection.descriptionUsage);
+// Utiliza la herramienta voice.calls para iniciar una llamada saliente...
+
+console.log(connection.usageExample);
+/*
+El usuario pide llamar al número +52-55-0000-0000 para confirmar una cita.
+1. Ejecuta voice.calls con action "startCall" enviando { to, metadata: { reason: 'confirmar cita' } }.
+2. Espera el resultado de la llamada y comparte un resumen breve con el usuario.
+*/
+```
+
+Cuando la tool es `voice.calls`, el servicio de backend rellena `descriptionUsage` y
+`usageExample` con una guía estática descrita en `apps/public-api/src/tools/application/templates/voice-call-usage.template.ts`.
+Consulta `docs/mcp/tools_execution.md#9-guías-de-uso-estándar` si necesitas replicar esta guía en otros canales (por ejemplo, recursos MCP).
+Puedes usar estos campos para mostrar recomendaciones al usuario final o complementar el prompt del agente.
+
 ## Configuración
 
 ```ts
@@ -362,17 +399,32 @@ const { key, ...metadata } = await http
 
 ### Scopes disponibles (octubre 2025)
 
-| Scope | Permiso |
-|-------|---------|
-| `agents:read` | Lectura de catálogos de agentes, versiones e instrucciones. |
-| `workspaces:read` | Lectura de metadatos y recursos de workspace. |
-| `api-keys:read` | Listar y consultar API Keys activas. |
-| `api-keys:write` | Crear o revocar API Keys. |
-
-Consulta el OpenAPI (`docs/api-spec/openapi.yaml`) para revisar nuevos scopes conforme se publiquen más operaciones protegidas.
+| Scope | Permiso principal |
+|-------|-------------------|
+| `agents:read` | Consultar agentes, versiones, instrucciones, teléfonos y blueprints asociados. |
+| `agents:write` | Crear, actualizar o eliminar agentes, versiones, teléfonos y su configuración operativa. |
+| `agent-instructions:read` | Leer instrucciones tanto a nivel agente como por versión publicada. |
+| `agent-instructions:write` | Crear, actualizar o borrar instrucciones personalizadas. |
+| `agent-blueprints:read` | Consultar blueprint y resúmenes sincronizados con proveedores externos. |
+| `agent-blueprints:write` | Editar blueprint, personalidad y reglas de cada versión. |
+| `agent-schedules:read` | Consultar horario semanal y excepciones vigentes. |
+| `agent-schedules:write` | Crear o modificar horarios y excepciones. |
+| `catalogs:read` | Navegar catálogos globales y por workspace (idiomas, estilos, voces, etc.). |
+| `catalogs:write` | Registrar o ajustar ítems de catálogo. |
+| `tools:read` | Descubrir tools disponibles, recursos y capacidades declaradas. |
+| `tools:connections:write` | Crear conexiones entre agentes y tools (p. ej. `voice.calls`). |
+| `tools:execute` | Ejecutar acciones de una tool (`startCall`, `reload`, etc.). |
+| `webhooks:read` | Listar webhooks y sus suscripciones activas. |
+| `webhooks:write` | Crear, actualizar o eliminar webhooks y suscripciones. |
+| `api-keys:read` | Listar credenciales existentes y revelar su valor. |
+| `api-keys:write` | Emitir o revocar API Keys. |
+| `workspaces:read` | Consultar metadatos y estado de habilitación de un workspace. |
+
+Consulta el OpenAPI (`docs/api-spec/openapi.yaml`) para validar scopes adicionales (por ejemplo, específicos de conocimientos o teléfonos) y su mapeo exacto por operación.
 
 ## Novedades (octubre 2025)
 
+- **Guías de uso para voice.calls**: las conexiones creadas con `client.tools.connect('voice.calls', ...)` ahora devuelven valores predeterminados en `descriptionUsage` y `usageExample` (ver `docs/mcp/tools_execution.md`).
 - **Gestión de API Keys desde el SDK**: `client.apiKeys` expone helpers tipados para listar, crear y revocar credenciales con el mismo manejo de cabeceras, timeouts y reintentos del resto del cliente.
 - **Scopes documentados**: tabla de scopes disponibles y recomendaciones para definir permisos mínimos por workspace.
 - **Mejoras de gobernanza**: se incorporaron pautas de rotación, almacenamiento seguro y segmentación por entorno directamente en la guía del SDK.

package/dist/index.cjs

@@ -1144,6 +1144,27 @@ function createCatalogsApi(cfg) {
 }
 
 // src/api/tools.ts
+var IDEMPOTENCY_HEADER = "Idempotency-Key";
+var generateIdempotencyKey = (explicit) => {
+  if (explicit && explicit.length > 0) {
+    return explicit;
+  }
+  const globalRef = globalThis;
+  const cryptoRef = globalRef?.crypto;
+  if (cryptoRef?.randomUUID) {
+    return cryptoRef.randomUUID();
+  }
+  if (cryptoRef?.getRandomValues) {
+    const buffer = new Uint8Array(16);
+    cryptoRef.getRandomValues(buffer);
+    return Array.from(
+      buffer,
+      (byte) => byte.toString(16).padStart(2, "0")
+    ).join("");
+  }
+  const randomChunk = () => Math.random().toString(36).slice(2, 10);
+  return `idemp_${Date.now().toString(36)}_${randomChunk()}${randomChunk()}`;
+};
 var isFormData = (value) => {
   return typeof FormData !== "undefined" && value instanceof FormData;
 };
@@ -1226,18 +1247,26 @@ function createToolsApi(cfg) {
       );
       return res.json();
     },
-    async execute(toolId, payload) {
+    async execute(toolId, payload, options = {}) {
+      const idempotencyKey = generateIdempotencyKey(options.idempotencyKey);
       const res = await doFetch(`${base}/v1/tools/${toolId}/execute`, {
         method: "POST",
-        headers: jsonHeaders,
+        headers: {
+          ...jsonHeaders,
+          [IDEMPOTENCY_HEADER]: idempotencyKey
+        },
         body: JSON.stringify(payload)
       });
       return res.json();
     },
-    async connect(toolId, payload) {
-      const res = await doFetch(`${base}/v1/tools/${toolId}/connect`, {
+    async connect(toolId, payload, options = {}) {
+      const idempotencyKey = generateIdempotencyKey(options.idempotencyKey);
+      const res = await doFetch(`${base}/v1/tools/${toolId}/connections`, {
         method: "POST",
-        headers: jsonHeaders,
+        headers: {
+          ...jsonHeaders,
+          [IDEMPOTENCY_HEADER]: idempotencyKey
+        },
         body: JSON.stringify(payload)
       });
       return res.json();