LangGraph y chat¶

Fuente del diagrama: docs/diagrams/guias-plugins-ai-agents-langgraph-01.mermaid en cortex-docs.

flowchart TB
  subgraph panel [Panel React]
    Chat[AgentChatWidget]
  end
  subgraph transport [Canal chat]
    WS["WS /api/v1/ws message ai-agents"]
  end
  subgraph plugin [cortex_plugin_ai_agents]
    Handler[ws_handler]
    Graph[LangGraph Agent]
    LLM[LLM Gemini free tier]
  end
  subgraph tools [Herramientas servidor]
    MCP[McpToolRegistry in-process]
    Core[core_hello]
    Plug[tools de plugins activos]
  end
  Chat --> WS --> Handler --> Graph
  Graph --> LLM
  Graph --> MCP
  MCP --> Core
  MCP --> Plug

Leyenda: WS = canal de chat del panel; MCP = tools en el servidor (registry in-process, no el browser). Estado: Implementado (beta).

Canal de chat (WebSocket)¶

El chat en Admin → Automatización → Agentes IA (/admin/agent) usa WebSocket como canal en tiempo real:

En desarrollo local el panel Vite (:5175) debe proxyar /api con WebSocket (ws: true en framework/web-shadcn/vite.config.ts). Sin eso el badge queda en Disconnected.

MCP no es el transporte del panel: el runtime Python carga tools desde McpToolRegistry in-process. POST /mcp queda para agentes externos.

Requisitos¶

• API en :8000 y panel en :5175 (o despliegue con proxy WS).
• Credencial con secreto en Configuración → Automatización → Credenciales.
• Conectores MCP en Configuración → Automatización → Conectores.
• Agente con credential_id, model, system y opcionalmente source.
• Redis 8+ o Redis Stack (opcional; si falla, MemorySaver en memoria).

Checklist local¶

1. En .env: NVIDIA_KEY=... y/o GEMINI_KEY=...; opcionalmente OPENAI_KEY / ANTHROPIC_KEY
2. UV_CACHE_DIR=/tmp/uv-cache uv run cortex-api
3. npm run dev:web-shadcn
4. Abrir /admin/agent → badge Connected
5. Enviar un mensaje en el chat
6. Botón MCP → lista tools (core_hello, ai_agents_list, …)

El agente demo (id 1) usa model: meta/llama-3.1-8b-instruct (NVIDIA Build) y credential_id: 4.

Variables de entorno¶

Copia .env.example a .env. No commits de .env.

Si Redis no está disponible, el plugin usa MemorySaver (los hilos se pierden al reiniciar el proceso).

Flujo¶

1. El panel envía mensajes por WebSocket (namespace: ai-agents, tipo chat).
2. Payload: { "message", "agentId", "threadId?" }.
3. El grafo ReAct resuelve LLM desde agente + credencial, carga tools desde el registry MCP in-process y persiste el hilo.
4. Respuesta: { "text", "threadId" } — el cliente guarda threadId en sessionStorage.

Proveedores soportados¶

Si el secreto está vacío, el chat responde con MISSING_CREDENTIAL_SECRET.

Tools MCP¶

El grafo descubre tools al iniciar cada invocación desde los conectores MCP activos.

El conector Cortex (slug cortex, url vacía) viene activo por defecto. Nombres internos: {namespace}_{action} (snake_case).