Construindo um Agente de IA Simples com Micronaut, MCP e LangChain4j

Um agente de IA é um sistema que utiliza um modelo de linguagem para entender instruções, decidir sobre ações e executá-las usando ferramentas disponíveis.
Na prática, como isso se parece?
Neste artigo, construímos um agente de IA simples para gerenciamento de tarefas em Java usando Micronaut, LangChain4j e Model Context Protocol (MCP). Ele demonstra como um agente interpreta linguagem natural, seleciona a ação correta e a executa de forma segura através de uma interface de ferramenta estruturada.

Código completo para este projeto está disponível aqui:

• https://github.com/jobinesh/java-ai-lab/tree/main/task-agent
• https://github.com/jobinesh/java-ai-lab/tree/main/task-mcp-server

O que é um Agente de IA?

Um agente de IA é um sistema de software que utiliza um modelo de linguagem para interpretar a entrada do usuário, raciocinar sobre ela e tomar ações invocando ferramentas ou APIs.

Em sua essência, um agente de IA consiste em:

1. Um modelo de raciocínio – tipicamente um LLM que entende as instruções do usuário
2. Um conjunto de ferramentas – funções ou APIs que o agente pode invocar
3. Um loop de execução – um ciclo de: → entender → decidir → agir → retornar resultado

Neste projeto, esse loop é implementado de forma limpa e explícita.

Como o agente funciona neste repositório

• TaskPlannerAiService (LangChain4j) solicita ao modelo que produza uma chamada de ferramenta JSON estruturada única
• TaskAgentOrchestrator analisa e valida esse JSON
• McpTaskClient executa a ferramenta selecionada via MCP

Esse design impõe uma regra importante:

O modelo nunca modifica diretamente os dados de negócios.
Ele apenas decide o que deve acontecer, enquanto o sistema controla como isso acontece.

O que é MCP (Model Context Protocol)?

Model Context Protocol (MCP) é um protocolo padronizado que define como os agentes de IA interagem com ferramentas e serviços externos de maneira estruturada e confiável.

Sem o MCP, as aplicações frequentemente implementam formatos de chamada de ferramenta personalizados, levando a integrações inconsistentes e sistemas frágeis.

O MCP fornece:

• Uma interface padrão para expor ferramentas
• Esquemas estruturados para argumentos de ferramentas
• Um modelo de comunicação baseado em JSON-RPC
• Uma separação clara entre decisão de IA e execução do sistema

Por que o MCP é importante

Neste projeto, o MCP fornece:

• Uma interface de ferramenta estável (create-task, list-tasks, complete-task, etc.)
• Argumentos estruturados e validados
• Um ciclo de vida previsível (initialize → tools/call)
• Acoplamento solto entre o agente e os serviços de backend

Em termos simples:

O MCP é o contrato entre o raciocínio da IA e as ações do mundo real.

Arquitetura do Projeto

Este projeto é dividido em dois módulos:

1. task-mcp-server — Servidor de Ferramentas MCP (Micronaut)

Este módulo expõe operações relacionadas a tarefas como ferramentas MCP usando Micronaut.

As ferramentas são definidas usando anotações como:

• @Tool(name = "create-task")
• @Tool(name = "list-tasks")
• @Tool(name = "complete-task")
• @Tool(name = "set-priority")

Todas as ferramentas operam em um TaskStore em memória.

💡 Detalhe chave:
Tanto as APIs REST quanto as ferramentas MCP compartilham o mesmo armazenamento. Portanto:

• Dados criados via REST são visíveis para o MCP
• Dados criados via MCP são visíveis para o REST

2. task-agent — Tempo de Execução do Agente de IA

Este módulo contém a camada de tomada de decisão impulsionada por IA.

Habilidades como configuração

Em vez de codificar o comportamento, o agente usa um arquivo skills.md:

@SystemMessage(fromResource = "skills.md")
@UserMessage("Instrução do usuário: {{instruction}}")
String plan(@V("instruction") String instruction);

Isso permite que você:

• Atualize o comportamento do agente sem recompilar
• Defina regras de uso de ferramentas em Markdown

Camada de Orquestração

TaskAgentOrchestrator é responsável por:

• Analisar a saída do modelo
• Validar a estrutura JSON
• Aplicar padrões seguros
• Chamar ferramentas MCP via McpTaskClient

Cliente MCP

McpTaskClient se comunica com o servidor MCP usando JSON-RPC:

• Endpoint: http://127.0.0.1:8080/mcp
• Fluxo: initialize → tools/call

Fluxo de Trabalho de Ponta a Ponta

Exemplo de instrução

"Criar tarefa Comprar leite com alta prioridade e marcar como casa"

Etapas de execução

1. O agente envia a instrução + definição de habilidades para o modelo
2. O modelo retorna JSON estruturado:

{
  "tool": "create-task",
  "arguments": {
    "title": "Comprar leite",
    "priority": "ALTA",
    "tags": "casa"
  }
}

1. O orquestrador analisa e valida o JSON
2. O cliente MCP chama create-task
3. O servidor MCP executa e retorna o resultado

Por que esse padrão funciona

Essa arquitetura é simples, mas poderosa.

Benefícios

• Adicionar novas ferramentas sem alterar a lógica do agente