Neonia

La plataforma definitiva para Agentes de IA Autónomos. Incluye Descubrimiento Autónomo de Herramientas (encuentra y ejecuta dinámicamente capacidades faltantes), Memoria en la Nube con Estado (recuerda el contexto entre sesiones), Empaquetado de Contexto (ahorra tokens de LLM) y más de 20 herramientas de desarrollo especializadas.

GitHub
5

Documentación

Ejemplos de Agente Neonia MCP

AI-Ready via Neonia

Una colección de ejemplos de agentes autónomos que demuestran cómo integrar el Gateway de Protocolo de Contexto de Modelo (MCP) de Neonia utilizando el estándar oficial de transporte HTTP Streamable.

Acerca de Estos Ejemplos

Este repositorio crecerá continuamente con nuevos patrones que demuestran agentes de IA deterministas y de alto rendimiento.

Nuestras primeras demostraciones principales se centran en resolver dos problemas críticos en las arquitecturas de agentes modernas: Hinchazón de la Ventana de Contexto y Rigidez de Herramientas.

1. Resolviendo la Rigidez de Herramientas (Descubrimiento Auto-Piloto)

Tradicionalmente, los agentes están codificados con una lista estática de herramientas. Si un usuario solicita algo fuera de esa lista, el agente alucina o falla. Los ejemplos de auto-discovery-url-to-markdown demuestran cómo dar a tus agentes verdadera autonomía. Al conectarse al Gateway de Neonia, el agente puede buscar dinámicamente capacidades faltantes, leer el esquema de la herramienta y ejecutarla sobre la marcha sin intervención humana.

2. Resolviendo la Hinchazón de Contexto (Procesamiento de Datos Cero-Hinchazón)

Tradicionalmente, cuando un agente necesita extraer datos de un archivo JSON grande de 5MB, carga todo el archivo en su ventana de contexto, causando un consumo masivo de tokens, alta latencia y "amnesia" del LLM. Al conectarse al Gateway MCP de Neonia (mcp.neonia.io/mcp?tools=neonia_data_jq_filter), nuestros agentes de zero-bloat-jq-filter vinculan explícitamente la herramienta Filtro JQ impulsado por Wasm. El agente ejecuta consultas en el servidor remoto y recibe solo el resultado filtrado (por ejemplo, $651,758.23), ahorrando ~50,000+ tokens por solicitud y respondiendo casi instantáneamente.

3. Nota de Memoria con Estado (stateful-cloud-memory)

Los agentes típicamente sufren de amnesia absoluta entre sesiones. Si un usuario establece una preferencia o regla de negocio, se pierde a menos que esté codificada en el prompt del sistema. Los ejemplos de stateful-cloud-memory demuestran cómo crear agentes con estado que utilizan la Arquitectura de Memoria Dual de Neonia (neonia_sys_memory_note para escritura y neonia_sys_memory_search para lectura) para almacenar y recuperar dinámicamente reglas (como personas personalizadas o preferencias de usuario) a través de sesiones completamente aisladas sin necesidad de una base de datos personalizada.

4. Memoria de Conocimiento Persistente (persistent-knowledge-memory)

Cuando los agentes aprenden lecciones arquitectónicas difíciles, correcciones de errores o reglas operativas estrictas, necesitan una forma de persistir este conocimiento utilizando una estructura estricta de Causa y Efecto (ADR). Los ejemplos de persistent-knowledge-memory demuestran el uso de la herramienta neonia_sys_memory_lesson para guardar conocimientos complejos para que agentes futuros puedan recuperarlos usando neonia_sys_memory_search antes de comenzar sus tareas.

(¡Pronto se agregarán más ejemplos que cubren extracción de visión, ejecución dinámica y orquestación multi-agente!)

Ejemplos Proporcionados

Este repositorio incluye implementaciones de "Procesamiento de Datos Cero-Hinchazón", "Descubrimiento de Herramientas Auto-Piloto" y "Nota de Memoria con Estado" en los principales marcos de agentes en 3 idiomas diferentes:

1. Python (LangGraph)

Un flujo de trabajo determinista que utiliza LangChain y LangGraph para construir un agente reactivo (create_agent) que envuelve dinámicamente las capacidades MCP en instancias nativas de @tool de LangChain.

  • Directorios: python/langgraph/zero-bloat-jq-filter, python/langgraph/chained-json-jq-filter, python/langgraph/auto-discovery-url-to-markdown, python/langgraph/stateful-cloud-memory, python/langgraph/persistent-knowledge-memory
  • Configuración: uv sync && uv run python agent.py

2. Python (SmolAgents)

Un agente autoensamblable que utiliza SmolAgents y LiteLLM de Hugging Face. Demuestra la subclasificación de smolagents.Tool para ejecución síncrona hacia adelante envuelta alrededor de una sesión HTTP Streamable asíncrona.

  • Directorios: python/smolagents/zero-bloat-jq-filter, python/smolagents/chained-json-jq-filter, python/smolagents/auto-discovery-url-to-markdown, python/smolagents/stateful-cloud-memory, python/smolagents/persistent-knowledge-memory
  • Configuración: uv sync && uv run python main.py

3. TypeScript (Vercel AI SDK)

Una integración con el Vercel AI SDK que utiliza los oficiales @modelcontextprotocol/sdk y @openrouter/ai-sdk-provider. Demuestra la llamada adecuada a herramientas de múltiples turnos y el mapeo de esquemas para Claude 3.7 Sonnet.

  • Directorios: typescript/vercel-ai-sdk/zero-bloat-jq-filter, typescript/vercel-ai-sdk/chained-json-jq-filter, typescript/vercel-ai-sdk/auto-discovery-url-to-markdown, typescript/vercel-ai-sdk/stateful-cloud-memory, typescript/vercel-ai-sdk/persistent-knowledge-memory
  • Configuración: npm install && npm start

4. Rust (Rig)

Una integración con tipado estático que utiliza el marco de agentes Rig y rust-mcp-sdk. Demuestra cómo conectar una sesión de cliente MCP inicializada al sistema de tipos fuerte de Rust.

  • Directorios: rust/rig/zero-bloat-jq-filter, rust/rig/chained-json-jq-filter, rust/rig/auto-discovery-url-to-markdown, rust/rig/stateful-cloud-memory, rust/rig/persistent-knowledge-memory
  • Configuración: cargo run

Requisitos Previos

Para ejecutar estos ejemplos, necesitarás:

  1. Una Clave API de Neonia (NEONIA_API_KEY)
  2. Una Clave API de OpenRouter (OPENROUTER_API_KEY)

Configúralas en el archivo .env dentro del directorio del ejemplo específico que desees ejecutar.

Arquitectura del Ecosistema

agent-mcp-examples/
├── typescript/                 # TypeScript Ecosystem
│   └── vercel-ai-sdk/          # Vercel AI SDK Framework
│       ├── zero-bloat-jq-filter/           # Single-tool Data Processing
│       ├── chained-json-jq-filter/         # Multi-tool Chained Data Processing
│       ├── auto-discovery-url-to-markdown/ # Auto-Pilot Tool Discovery
│       ├── stateful-cloud-memory/          # System Memory Note Persistence
│       └── persistent-knowledge-memory/    # Architectural Lesson Persistence
│
├── python/                     # Python Ecosystem
│   ├── langgraph/              # LangGraph Framework
│   │   ├── zero-bloat-jq-filter/
│   │   ├── chained-json-jq-filter/
│   │   ├── auto-discovery-url-to-markdown/
│   │   ├── stateful-cloud-memory/
│   │   └── persistent-knowledge-memory/
│   └── smolagents/             # SmolAgents Framework
│       ├── zero-bloat-jq-filter/
│       ├── chained-json-jq-filter/
│       ├── auto-discovery-url-to-markdown/
│       ├── stateful-cloud-memory/
│       └── persistent-knowledge-memory/
│
└── rust/                       # Rust Ecosystem
    └── rig/                    # Rig Framework
        ├── zero-bloat-jq-filter/
        ├── chained-json-jq-filter/
        ├── auto-discovery-url-to-markdown/
        ├── stateful-cloud-memory/
        └── persistent-knowledge-memory/

Ejemplos Disponibles

Cada ejemplo es autónomo y demuestra patrones arquitectónicos específicos y listos para producción sobre MCP.

1. Descubrimiento de Herramientas Auto-Piloto (auto-discovery-url-to-markdown)

Demuestra cómo dar a los agentes verdadera autonomía. Si un agente carece de una capacidad requerida, busca dinámicamente en el Gateway de Neonia una herramienta que coincida, lee sus parámetros y la ejecuta sobre la marcha sin intervención humana.

2. Procesamiento de Datos Cero-Hinchazón (zero-bloat-jq-filter)

Demuestra cómo procesar de manera segura cargas útiles masivas de API utilizando un filtro JQ Wasm determinista en el borde, reduciendo drásticamente el uso de contexto de tokens del LLM y previniendo la alucinación.

3. Ejecución de Datos Encadenada (chained-json-jq-filter)

Demuestra cómo procesar de manera segura cargas útiles masivas de API utilizando un flujo de trabajo de datos encadenado. El agente utiliza neonia_web_json_fetch para recuperar JSON remoto y lo almacena en el Gateway, devolviendo un puntero ligero. Luego pasa este puntero a un filtro JQ Wasm determinista (neonia_data_jq_filter) para extraer exactamente lo que necesita, manteniendo su ventana de contexto increíblemente pequeña.

4. Nota de Memoria con Estado (stateful-cloud-memory)

Demuestra cómo utilizar la Arquitectura de Memoria Dual (neonia_sys_memory_note y neonia_sys_memory_search) para permitir que un agente recuerde personas o reglas de negocio a través de sesiones completamente aisladas.

5. Memoria de Conocimiento Persistente (persistent-knowledge-memory)

Demuestra cómo utilizar la Arquitectura de Memoria Dual (neonia_sys_memory_lesson y neonia_sys_memory_search) para permitir que un agente registre lecciones arquitectónicas difíciles en un formato de causa y efecto y las recupere dinámicamente en nuevas tareas.

Comenzando

Para ejecutar los ejemplos, necesitarás una clave API de Anthropic (para el agente de IA) y una clave API gratuita de Neonia (para el Gateway MCP Wasm).

  1. Clona el repositorio:

    git clone https://github.com/neonia-io/agent-mcp-examples.git
cd agent-mcp-examples

  2. Navega al ejemplo que deseas probar:

    cd typescript/vercel-ai-sdk/zero-bloat-jq-filter

  3. Configura las variables de entorno:

    OPENROUTER_API_KEY="your-openrouter-key"
NEONIA_API_KEY="your-neonia-key"

    (Nota: El Gateway de Neonia requiere una clave API gratuita para autenticar las conexiones MCP).

  4. Instala las dependencias y ejecuta:

    npm install
npx tsx index.ts