Neonia

A plataforma definitiva para Agentes de IA Autônomos. Recursos incluem Descoberta Autônoma de Ferramentas (encontra e executa dinamicamente capacidades ausentes), Memória em Nuvem com Estado (lembra do contexto entre sessões), Empacotamento de Contexto (economiza tokens de LLM) e mais de 20 ferramentas de desenvolvimento especializadas.

GitHub
5

Documentação

Exemplos de Agente Neonia MCP

AI-Ready via Neonia

Uma coleção de exemplos de agentes autônomos demonstrando como integrar o Gateway Neonia Model Context Protocol (MCP) usando o padrão oficial de transporte Streamable HTTP.

Sobre Estes Exemplos

Este repositório crescerá continuamente com novos padrões demonstrando agentes de IA determinísticos e de alta performance.

Nossos primeiros grandes destaques focam em resolver dois problemas críticos em arquiteturas modernas de agentes: Inchaço da Janela de Contexto e Rigidez de Ferramentas.

1. Resolvendo Rigidez de Ferramentas (Descoberta Auto-Piloto)

Agentes são tradicionalmente codificados com uma lista estática de ferramentas. Se um usuário pedir algo fora dessa lista, o agente alucina ou falha. Os exemplos auto-discovery-url-to-markdown demonstram como dar aos seus agentes verdadeira autonomia. Ao conectar-se ao Gateway Neonia, o agente pode buscar dinamicamente por capacidades ausentes, ler o esquema da ferramenta e executá-la em tempo real sem intervenção humana.

2. Resolvendo Inchaço de Contexto (Processamento de Dados Zero-Bloat)

Tradicionalmente, quando um agente precisa extrair dados de um grande arquivo JSON de 5MB, ele carrega o arquivo inteiro em sua janela de contexto, causando consumo massivo de tokens, alta latência e "amnésia" do LLM. Ao conectar-se ao Gateway MCP Neonia (mcp.neonia.io/mcp?tools=neonia_data_jq_filter), nossos agentes zero-bloat-jq-filter vinculam explicitamente a ferramenta Filtro JQ com Wasm. O agente executa consultas no servidor remoto e recebe apenas o resultado filtrado (ex.: $651,758.23), economizando ~50.000+ tokens por requisição e respondendo quase instantaneamente.

3. Nota de Memória com Estado (stateful-cloud-memory)

Agentes tipicamente sofrem de amnésia absoluta entre sessões. Se um usuário declara uma preferência ou regra de negócio, ela é perdida a menos que seja codificada no prompt do sistema. Os exemplos stateful-cloud-memory demonstram como criar agentes com estado que usam a Arquitetura de Memória Dupla da Neonia (neonia_sys_memory_note para escrita e neonia_sys_memory_search para leitura) para armazenar e recuperar dinamicamente regras (como personas personalizadas ou preferências do usuário) entre sessões completamente isoladas, sem precisar de um banco de dados personalizado.

4. Memória de Conhecimento Persistente (persistent-knowledge-memory)

Quando agentes aprendem lições arquiteturais difíceis, correções de bugs ou regras operacionais estritas, eles precisam de uma forma de persistir esse conhecimento usando uma estrutura estrita de Causa e Efeito (ADR). Os exemplos persistent-knowledge-memory demonstram o uso da ferramenta neonia_sys_memory_lesson para salvar insights complexos para que agentes futuros possam recuperá-los usando neonia_sys_memory_search antes de iniciar suas tarefas.

(Mais exemplos cobrindo extração de visão, execução dinâmica e orquestração multi-agente serão adicionados em breve!)

Exemplos Fornecidos

Este repositório inclui implementações de "Processamento de Dados Zero-Bloat", "Descoberta de Ferramentas Auto-Piloto" e "Nota de Memória com Estado" em frameworks agenticos importantes em 3 idiomas diferentes:

1. Python (LangGraph)

Um fluxo de trabalho determinístico usando LangChain e LangGraph para construir um agente reativo (create_agent) que envolve dinamicamente capacidades MCP em instâncias nativas de @tool do LangChain.

  • Diretórios: 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
  • Configuração: uv sync && uv run python agent.py

2. Python (SmolAgents)

Um agente auto-montável usando SmolAgents e LiteLLM da Hugging Face. Demonstra a subclasse smolagents.Tool para execução síncrona de encaminhamento envolvida em uma sessão assíncrona Streamable HTTP.

  • Diretórios: 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
  • Configuração: uv sync && uv run python main.py

3. TypeScript (Vercel AI SDK)

Uma integração com o Vercel AI SDK utilizando os oficiais @modelcontextprotocol/sdk e @openrouter/ai-sdk-provider. Demonstra chamadas de ferramentas multi-turno adequadas e mapeamento de esquema para Claude 3.7 Sonnet.

  • Diretórios: 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
  • Configuração: npm install && npm start

4. Rust (Rig)

Uma integração estaticamente tipada usando o framework de agentes Rig e rust-mcp-sdk. Demonstra a ponte de uma sessão de cliente MCP inicializada no sistema de tipos forte do Rust.

  • Diretórios: 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
  • Configuração: cargo run

Pré-requisitos

Para executar estes exemplos, você precisará de:

  1. Uma Chave de API Neonia (NEONIA_API_KEY)
  2. Uma Chave de API OpenRouter (OPENROUTER_API_KEY)

Configure-as no arquivo .env dentro do diretório do exemplo específico que deseja executar.

Arquitetura do Ecossistema

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/

Exemplos Disponíveis

Cada exemplo é autossuficiente e demonstra padrões arquiteturais específicos e prontos para produção sobre MCP.

1. Descoberta de Ferramentas Auto-Piloto (auto-discovery-url-to-markdown)

Demonstra como dar aos agentes verdadeira autonomia. Se um agente não possui uma capacidade necessária, ele busca dinamicamente no Gateway Neonia por uma ferramenta correspondente, lê seus parâmetros e a executa em tempo real sem intervenção humana.

2. Processamento de Dados Zero-Bloat (zero-bloat-jq-filter)

Demonstra como processar com segurança cargas úteis massivas de API usando um filtro JQ Wasm determinístico na borda, reduzindo drasticamente o uso de contexto de tokens do LLM e prevenindo alucinações.

3. Execução de Dados em Cadeia (chained-json-jq-filter)

Demonstra como processar com segurança cargas úteis massivas de API usando um fluxo de trabalho de dados em cadeia. O agente usa neonia_web_json_fetch para recuperar JSON remoto e o armazena no Gateway, retornando um ponteiro leve. Ele então passa esse ponteiro para um filtro JQ Wasm determinístico (neonia_data_jq_filter) para extrair exatamente o que precisa, mantendo sua janela de contexto incrivelmente pequena.

4. Nota de Memória com Estado (stateful-cloud-memory)

Demonstra como usar a Arquitetura de Memória Dupla (neonia_sys_memory_note e neonia_sys_memory_search) para permitir que um agente lembre de personas ou regras de negócio entre sessões completamente isoladas.

5. Memória de Conhecimento Persistente (persistent-knowledge-memory)

Demonstra como usar a Arquitetura de Memória Dupla (neonia_sys_memory_lesson e neonia_sys_memory_search) para permitir que um agente registre lições arquiteturais difíceis em um formato de causa e efeito e as recupere dinamicamente em novas tarefas.

Começando

Para executar os exemplos, você precisará de uma chave de API Anthropic (para o agente de IA) e uma chave de API Neonia gratuita (para o Gateway MCP Wasm).

  1. Clone o repositório:

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

  2. Navegue até o exemplo que deseja experimentar:

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

  3. Configure as variáveis de ambiente:

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

    (Nota: O Gateway Neonia requer uma chave de API gratuita para autenticar conexões MCP).

  4. Instale as dependências e execute:

    npm install
npx tsx index.ts