Construindo um Motor de Ferramentas com Spring AI — Como Demos ao Jarvis a Capacidade de Agir no Mundo

De saber a fazer — Fase 4 da Plataforma de IA Jarvis

O Problema com a IA Apenas de Conhecimento

Após a Fase 3, Jarvis podia se lembrar de você entre as sessões e pesquisar seus documentos.

Mas ainda tinha uma limitação fundamental.

Você: "Qual é o clima em Katmandu agora?"
Jarvis: "Eu não tenho acesso a dados climáticos em tempo real."

Você: "Qual é 2847 × 391?"
Jarvis: "A resposta é aproximadamente 1,1 milhão." ← ERRADO

Uma IA que apenas conhece coisas a partir de dados de treinamento é útil.

Uma IA que pode fazer coisas é transformadora.

Isso é o que a Fase 4 construiu.

O que é um Motor de Ferramentas?

Um motor de ferramentas dá ao modelo de IA a capacidade de chamar funções reais durante uma conversa.

O fluxo é assim:

Usuário: "Qual é o clima em Katmandu?"
            ↓
        Modelo de IA
            ↓
  "Eu devo chamar WeatherTool"
            ↓
    WeatherTool.getWeather("Katmandu")
            ↓
    "22°C, Céu limpo, Umidade: 45%"
            ↓
        Modelo de IA
            ↓
"O clima em Katmandu é 22°C e limpo."

A chave é a percepção: a IA decide quando chamar uma ferramenta e com qual entrada.

Não codificamos "se o usuário perguntar sobre o clima, chame WeatherTool".

O modelo descobre isso a partir das descrições das ferramentas que fornecemos.

A Decisão de Arquitetura

A decisão arquitetônica mais importante na Fase 4 foi a estrutura do pacote.

ai.jarvis.tools/
├── JarvisTool.java          ← interface marcadora (raiz)
├── ToolRegistry.java        ← gerencia todas ferramentas (raiz)
├── builtin/                 ← ferramentas embutidas
│   ├── DateTimeTool.java
│   ├── CalculatorTool.java
│   ├── WeatherTool.java
│   └── WebSearchTool.java
└── mcp/                     ← protocolo MCP
    └── McpServerConfig.java

Por que não colocar ferramentas dentro ai/?

O ai/ pacote lida com COMO Jarvis se comunica com modelos de IA.

As ferramentas definem O QUE Jarvis pode fazer.

Essas são responsabilidades fundamentalmente diferentes.

Misturá-las significaria que cada nova ferramenta exigiria mudanças no código da infraestrutura de IA.

Mantê-las separadas significa que adicionar uma nova ferramenta requer exatamente um arquivo.

O Padrão JarvisTool

Cada ferramenta no Jarvis implementa uma interface.

/**
 * Interface marcadora para todas as ferramentas Jarvis.
 * O Spring descobre automaticamente todas as implementações @Component.
 * ToolRegistry coleta todas automaticamente.
 * Adicionar uma nova ferramenta = apenas adicionar @Component.
 */
public interface JarvisTool {
    // Interface marcadora — nenhum método necessário
}

Esse é o Padrão de Estratégia em sua forma mais simples.

A anotação @Tool nos métodos informa ao Spring AI o que cada função faz e quando a IA deve chamá-la.

@Component
public class WeatherTool implements JarvisTool {

    @Tool(description =
            "Obter condições climáticas atuais para qualquer cidade. "
                    + "Usar quando o usuário perguntar sobre clima, "
                    + "temperatura ou clima.")
    public String getWeather(
            @ToolParam(description = "Nome da cidade em inglês")
            String cidade) {
        // Chamada real da API OpenWeatherMap
        return "Katmandu: 22°C, Céu limpo";
    }
}

Três coisas fazem isso funcionar bem:

A descrição é extremamente importante.

A IA lê a descrição para decidir se deve chamar esta ferramenta. Uma descrição vaga como "ferramenta de clima" produz resultados pouco confiáveis. Uma descrição específica que explica exatamente quando usá-la produz resultados consistentemente bons.

Nunca lance exceções para a IA.

Se a API estiver fora do ar, retorne uma string de erro amigável. A IA pode então informar ao usuário que algo deu errado em vez de travar toda a sessão.

Retorne strings simples.

Cada ferramenta retorna String. A IA lida com a formatação. Mantenha as ferramentas focadas na recuperação de dados, não na apresentação.

O ToolRegistry

Quando o Spring inicia, ele descobre automaticamente cada classe anotada com @Component que implementa JarvisTool.

@Component
public class ToolRegistry {

    private final List<JarvisTool> ferramentas;

    // O Spring injeta TODOS os beans JarvisTool automaticamente
    public ToolRegistry(