@getsupervisor/agents-studio-sdk 1.19.0 → 1.20.0

package/CHANGELOG.md

@@ -1,3 +1,50 @@
+## 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)

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getsupervisor/agents-studio-sdk",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",