Primeros pasos

En esta guía creas un stack mínimo — una cuenta de proveedor, un modelo y un agente — y lo despliegas. Sirve igual si eres una persona usando el portal o un agente de IA trabajando por API: cada paso muestra ambas rutas.

0. Lo que necesitas

• Acceso al portal de Cortex con tu organización, o una API key del tenant con los scopes iac:manage (validar y proponer) e iac:deploy (ejecutar).
• La API key del proveedor de LLM que va a usar tu agente (por ejemplo, una key de OpenAI).

Para los ejemplos por API define estas variables:

export CORTEX_API_URL="https://cortex.opensolvex.co" # http://localhost:3006 en desarrollo
export CORTEX_API_KEY="osx_sk_xxx"                   # tu key con scopes iac:*
export OPENAI_API_KEY="sk-xxx"                       # la key del proveedor de LLM

1. Escribe el template

Guarda esto como template.yaml. Declara los tres recursos y cómo se conectan (!Ref), y recibe la API key del proveedor por un parámetro noEcho — nunca la escribas en el YAML:

version: "2026-07"
description: Mi primer agente en Cortex
parameters:
  OpenaiApiKey:
    type: string
    noEcho: true
resources:
  Cuenta:
    type: Cortex::ProviderAccount
    properties:
      provider: openai
      label: principal
      apiKey: !Ref OpenaiApiKey
  Modelo:
    type: Cortex::Model
    properties:
      accountId: !Ref Cuenta
      modelName: gpt-4o
  Asistente:
    type: Cortex::Agent
    properties:
      name: mi-asistente
      systemPrompt: Eres el asistente de soporte de mi empresa. Responde breve y en español.
      modelId: !Ref Modelo
outputs:
  agentId: !GetAtt Asistente.id

2. Valida el template

La validación es un dry-run puro: no crea nada. Revisa sintaxis, tipos de recurso, referencias, ciclos y las propiedades de cada recurso contra su gestor.

Portal: el editor valida en vivo mientras escribes (o con ⌘S).

API:

curl -X POST "$CORTEX_API_URL/v1/iac/templates/validate" \
  -H "x-api-key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile t template.yaml '{template: $t}')"

Si es válido responde 200 con los recursos detectados y el orden de despliegue; si no, 422 con la lista de errores y la ruta exacta de cada uno (resources.Modelo.properties…).

3. Crea el stack

Crear el stack no materializa nada todavía: queda en estado REVIEW_IN_PROGRESS con un changeset pendiente que describe todo lo que se va a crear. El nombre del stack va en kebab-case (mi-primer-stack) y es único en tu tenant.

Portal: Stacks → Nuevo stack. Elige una plantilla de la galería o pega la tuya, ponle nombre, completa los parámetros (los noEcho se piden como contraseña) y crea. Aterrizas en el detalle, en la pestaña de changesets.

API:

curl -X POST "$CORTEX_API_URL/v1/iac/stacks" \
  -H "x-api-key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile t template.yaml \
    '{name: "mi-primer-stack", template: $t, parameters: {OpenaiApiKey: env.OPENAI_API_KEY}}')"

La respuesta trae el stack (guarda su id) y el changeSet inicial (guarda su id también). Los valores noEcho que enviaste no vuelven en ninguna respuesta.

4. Revisa el diff

El changeset lista cada operación: add, modify, replace o remove, con los campos que cambian. Para un stack nuevo verás tres add en orden: Cuenta, Modelo, Asistente.

curl "$CORTEX_API_URL/v1/iac/stacks/$STACK_ID/change-sets" \
  -H "x-api-key: $CORTEX_API_KEY"

5. Ejecuta el changeset

Portal: botón Ejecutar en el changeset pendiente (si hay cambios destructivos, te pide confirmarlos explícitamente).

API:

curl -X POST "$CORTEX_API_URL/v1/iac/stacks/$STACK_ID/change-sets/$CHANGESET_ID/execute" \
  -H "x-api-key: $CORTEX_API_KEY"

Responde 202: el despliegue es asíncrono. Cortex aplica los recursos uno a uno en orden topológico; si alguno falla, revierte automáticamente lo ya aplicado.

6. Espera el resultado

Consulta el stack hasta que salga de CREATE_IN_PROGRESS:

curl "$CORTEX_API_URL/v1/iac/stacks/$STACK_ID" -H "x-api-key: $CORTEX_API_KEY"

• CREATE_COMPLETE — listo. El campo outputs trae tu agentId, y resources mapea cada nombre lógico a su id físico.
• ROLLBACK_COMPLETE — algo falló y se revirtió. Mira statusReason y la traza de eventos:

curl "$CORTEX_API_URL/v1/iac/stacks/$STACK_ID/events" -H "x-api-key: $CORTEX_API_KEY"

En el portal, la pestaña Eventos muestra esta traza en vivo (estilo CloudFormation) y la pestaña Recursos enlaza cada recurso a su pantalla nativa.

7. Actualiza el stack

Para cambiar algo, edita el template y propón un nuevo changeset — nunca se aplica directo:

curl -X POST "$CORTEX_API_URL/v1/iac/stacks/$STACK_ID/change-sets" \
  -H "x-api-key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile t template.yaml '{template: $t}')"

Revisa el diff y ejecútalo igual que antes. Re-aplicar el mismo template produce un diff vacío: el motor es idempotente.

Siguientes pasos

• Agrega secretos, tools, skills, hooks y enrutamiento a tu template para un agente completo.
• Entiende los estados, el rollback y la eliminación con retain.
• Si integras desde CI o desde un agente, revisa la referencia completa de la API.