> ## Documentation Index > Fetch the complete documentation index at: https://docs.getsupervisor.ai/llms.txt > Use this file to discover all available pages before exploring further. # Crear un stage dentro del blueprint del agente > Persiste un nuevo stage en el blueprint editable del agente. Antes de guardar se ejecuta la validación completa del grafo; en caso de error se responde `400 INVALID_GRAPH`. Una vez confirmada la creación se emite un evento `BlueprintStageCreated` que desencadena el job interno `StagesSyncJob` para reflejar los cambios en el proveedor de forma asincrónica. ## OpenAPI ````yaml /openapi/public-api.yaml post /v1/agents/{agentId}/stages openapi: 3.1.0 info: title: Agents Studio API version: 1.0.0 description: > API del backend de Agents Studio. Expone servicios multi-tenant para gestionar agentes (texto y voz), catálogo de herramientas, habilitación de workspaces y operaciones de telefonía. Todos los endpoints requieren autenticación Bearer y respetan los contratos documentados en `docs/modules`. license: name: Proprietary url: https://getsupervisor.ai/legal/terms servers: - url: https://api-prod.studio.getsupervisor.ai description: Producción - url: https://sandbox.agents.studio.getsupervisor.ai description: Sandbox security: - BearerAuth: [] tags: - name: Agents description: > Gestión general de agentes y sus metadatos. Scopes requeridos: `agents:read` para consultas y `agents:write` para creación, actualización y operaciones sobre teléfonos. - name: Agent Versions description: Versionado y mantenimiento de versiones publicadas de los agentes. - name: Agent Schedules description: >- Configuración de horarios regulares y excepciones puntuales para controlar la disponibilidad de los agentes. - name: Agent Knowledge description: Uploads y sincronización de knowledge bases asociadas al agente. - name: Agent Tags description: Gestión de etiquetas asociadas a agentes. - name: Campaigns description: > Gestión de campañas masivas basadas en CSV para ejecutar agentes de forma batch. Scopes requeridos: `campaigns:read` para consultas y `campaigns:write` para creación. - name: Calls description: | Consultas de llamadas (Speech Analytics) disponibles para el workspace. Scopes requeridos: `calls:read`. - name: Knowledge description: Gestión de recursos de conocimiento asociados a tools. - name: Agent Instructions description: > Operaciones sobre instrucciones (prompt) gestionadas por los usuarios finales para guiar y corregir el comportamiento del agente. Las instrucciones se aplican a la versión activa del agente, se mantienen como texto libre sin formato (1 a 500 caracteres) y su prioridad se controla mediante el campo `order`. Scopes requeridos: `agent-instructions:read` para consultas y `agent-instructions:write` para creación o edición. - name: Voices description: Catálogo consolidado de voces provenientes de proveedores externos. - name: Catalogs description: > Gestión centralizada de catálogos (idiomas, tonos, voces, etiquetas) con alcance global o específico por workspace. Scopes requeridos: `catalogs:read` para consultas y `catalogs:write` para creación y modificaciones. - name: Agent Phones description: Conexión y desconexión de teléfonos asignados a agentes. - name: API Keys description: Gestión de credenciales de acceso programático y sus permisos. - name: Agent Blueprints description: > Gestión del blueprint (personalidad) asociado a cada versión de agente. Scopes requeridos: `agent-blueprints:read` para lectura y `agent-blueprints:write` para cambios en blueprint. - name: Agent Stages description: > Autoría de stages del blueprint del agente, abarcando orden, prompts y validaciones previas a la publicación. Scopes requeridos: `stages:read` para consultas y `stages:write` para creación y edición. La validación se ejecuta automáticamente en cada mutación y la sincronización con proveedores sucede mediante jobs internos tras los cambios. - name: Stage Triggers description: > Gestión detallada de triggers que conectan stages dentro del blueprint y definen las transiciones conversacionales. Scopes requeridos: `stage-triggers:*` (o políticas equivalentes bajo `stages:*`). - name: Workspaces description: Gestión multi-tenant y habilitación de credenciales por workspace. - name: Tools description: > Catálogo y ejecución de tools disponibles para los agentes. Scopes requeridos: `tools:read` para listar y `tools:execute` para ejecutar tools. - name: Webhooks description: > Gestión de webhooks por workspace para suscribirse a eventos del dominio y recibir notificaciones HTTP. Scopes requeridos: `webhooks:read` para consultas y `webhooks:write` para crear, actualizar o eliminar webhooks y suscripciones. paths: /v1/agents/{agentId}/stages: post: tags: - Agent Stages summary: Crear un stage dentro del blueprint del agente description: > Persiste un nuevo stage en el blueprint editable del agente. Antes de guardar se ejecuta la validación completa del grafo; en caso de error se responde `400 INVALID_GRAPH`. Una vez confirmada la creación se emite un evento `BlueprintStageCreated` que desencadena el job interno `StagesSyncJob` para reflejar los cambios en el proveedor de forma asincrónica. operationId: createAgentStage parameters: - $ref: '#/components/parameters/XWorkspaceId' - $ref: '#/components/parameters/AgentId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBlueprintStageRequest' examples: createStage: summary: Stage con trigger de transición value: name: qualification title: Calificación goalPrompt: >- Haz preguntas abiertas para entender el contexto y valida si el lead cumple criterios. promptInstructions: - Pregunta por el presupuesto disponible - Valida el uso actual de soluciones order: 2 triggers: - condition: type: expression value: lead.qualified == true nextStageName: closing metadata: author: playbook@agents.studio responses: '201': description: Stage creado correctamente content: application/json: schema: $ref: '#/components/schemas/BlueprintStage' examples: created: summary: Stage registrado con trigger inicial value: id: b0d32725-47cc-43b3-b415-1304ca4f9e24 agentId: 38f62697-0f4b-49bc-8a0c-67256f5af6ff blueprintId: c09f3fa9-5082-4b0e-96b8-7426e672d88a name: qualification title: Calificación goalPrompt: >- Haz preguntas abiertas para entender el contexto y valida si el lead cumple criterios. promptInstructions: - Pregunta por el presupuesto disponible - Valida el uso actual de soluciones order: 2 triggers: - id: a02a4142-8279-42b3-98a2-71ef712d9c25 stageId: b0d32725-47cc-43b3-b415-1304ca4f9e24 blueprintId: c09f3fa9-5082-4b0e-96b8-7426e672d88a condition: type: expression value: lead.qualified == true nextStageName: closing createdAt: '2025-10-05T19:47:55.000Z' updatedAt: '2025-10-05T19:47:55.000Z' metadata: author: playbook@agents.studio createdAt: '2025-10-05T19:47:55.000Z' updatedAt: '2025-10-05T19:47:55.000Z' '400': description: >- Payload inválido (por ejemplo, nombre duplicado dentro del blueprint) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: INVALID_STAGE message: El nombre debe ser único dentro del blueprint '404': description: Blueprint o referencias asociadas no encontradas content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: BLUEPRINT_NOT_FOUND message: No se encontró un blueprint editable para el agente '409': description: Conflicto con el estado actual del blueprint content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: BLUEPRINT_LOCKED message: El blueprint publicado no admite nuevas modificaciones components: parameters: XWorkspaceId: name: x-workspace-id in: header required: true description: Identificador del workspace multi-tenant. schema: type: string format: uuid AgentId: name: agentId in: path required: true description: Identificador del agente schema: type: string format: uuid schemas: CreateBlueprintStageRequest: type: object properties: name: type: string minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ description: >- Nombre slug utilizado para referenciar el stage desde otros triggers. title: type: - string - 'null' goalPrompt: type: string minLength: 1 promptInstructions: type: array items: type: string default: [] order: type: - integer - 'null' minimum: 0 triggers: type: - array - 'null' items: $ref: '#/components/schemas/BlueprintStageTriggerInput' description: Triggers opcionales que se crearán junto con el stage. metadata: type: - object - 'null' additionalProperties: true required: - name - goalPrompt additionalProperties: false BlueprintStage: type: object properties: id: type: string format: uuid agentId: type: string format: uuid blueprintId: type: string format: uuid name: type: string minLength: 1 description: >- Nombre estable del stage (slug amigable para referencias entre triggers). title: type: - string - 'null' description: Título legible que se muestra en el editor. goalPrompt: type: string minLength: 1 description: Objetivo del stage expresado como prompt de alto nivel. promptInstructions: type: array description: Lista ordenada de instrucciones que contextualizan el goal prompt. items: type: string default: [] order: type: integer description: Posición del stage dentro del blueprint. triggers: type: array description: Triggers asociados al stage. items: $ref: '#/components/schemas/BlueprintStageTrigger' default: [] metadata: type: - object - 'null' additionalProperties: true description: Campos adicionales definidos por el workspace. contentHash: type: - string - 'null' description: Hash del contenido del stage utilizado para invalidar caches. variables: type: array description: Variables detectadas en el goal prompt e instrucciones del stage. items: type: string default: [] createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - agentId - blueprintId - name - goalPrompt - promptInstructions - order - triggers - contentHash - variables - createdAt - updatedAt additionalProperties: false ErrorResponse: type: object properties: code: type: string description: Código principal del error (alto nivel). message: type: string description: Mensaje legible para humanos. details: type: object description: > Información adicional específica del error. Cuando aplique, `details.subcode` provee un identificador estable para que el frontend decida qué UI mostrar. properties: subcode: type: string description: >- Identificador específico del error (p.ej. `WORKSPACE_NOT_PROVISIONED`). workspaceId: type: string format: uuid description: Identificador de workspace relacionado cuando aplica. additionalProperties: true required: - code - message BlueprintStageTriggerInput: type: object description: Payload base para crear o actualizar triggers asociados a un stage. properties: condition: $ref: '#/components/schemas/BlueprintStageTriggerCondition' nextStageName: type: string minLength: 1 required: - condition - nextStageName additionalProperties: false BlueprintStageTrigger: type: object properties: id: type: string format: uuid stageId: type: string format: uuid blueprintId: type: string format: uuid condition: $ref: '#/components/schemas/BlueprintStageTriggerCondition' nextStageName: type: string description: Nombre del siguiente stage al que se transicionará. createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - stageId - blueprintId - condition - nextStageName - createdAt - updatedAt additionalProperties: false BlueprintStageTriggerCondition: type: object description: Condición evaluada para activar la transición al siguiente stage. properties: type: type: string enum: - intent - rule - expression value: type: string description: >- Valor que representa la condición (intent esperado, expresión DSL, etc.). metadata: type: - object - 'null' additionalProperties: true description: Campos adicionales dependientes del proveedor. required: - type - value additionalProperties: false securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ````