Talentos Gateway na Solon AI: OpenAPI, Ferramenta e Superfícies MCP que Escalam sem Explosão de Contexto

Quando um agente pode ver 80 ferramentas ao mesmo tempo, o modelo não fica mais inteligente. Ele fica mais barulhento. As contas de tokens aumentam, a escolha da ferramenta se desvia e um simples prompt de “verificar status do pedido” de repente carrega metade da superfície OpenAPI da sua empresa.

O Solon AI (v4.0.3) responde a isso com o trio de Talentos Gateway em solon-ai-talent-gateway:

Todos os três compartilham o mesmo modelo de descoberta adaptativa em quatro estágios. Catálogos pequenos permanecem totalmente expandidos. Catálogos grandes se dobram em resumo → lista de nomes → pesquisa, para que o LLM pague apenas pelo que precisa.

Este artigo se concentra em APIs oficiais de article/1353, article/1389, article/1335, e article/1293.

Por que um gateway é um Talento, não “apenas mais ferramentas”

No Solon AI, uma Ferramenta é uma função atômica. Um Talento empacota ferramentas com instruções, ativação e restrições no estilo SOP.

Gateways precisam desse empacotamento:

• muitos esquemas brutos estouram o contexto
• ferramentas de diferentes sistemas precisam de agrupamento e ciclo de vida
• o modelo deve descobrir a capacidade passo a passo, não engolir tudo na primeira vez

É por isso que você conecta gateways com defaultTalentAdd(...) (ou talentAdd com escopo de solicitação), não despejando toda operação OpenAPI em defaultToolAdd.

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-ai-talent-gateway</artifactId>
</dependency>

Os recursos MCP também precisam de solon-ai-mcp. A análise OpenAPI puxa o swagger-parser (v2 e v3); exclua-o apenas se você nunca carregar documentos.

Os quatro estágios (compartilhados por todos os três gateways)

Regra de design dos documentos: quando o catálogo é pequeno, incorpore esquemas completos na instrução para que o modelo possa chamar em um passo; quando cresce, dobre a informação e force a descoberta progressiva.

Controles compartilhados:

1. OpenApiGatewayTalent — transforme Swagger em uma superfície de agente

Use isso quando as ferramentas já existirem como documentos OpenAPI / Swagger (remoto http:// ou local classpath:).

Capacidades oficialmente destacadas:

• Detecção automática do Swagger 2.0 + OpenAPI 3.0
• carregamento de múltiplas fontes com agrupamento baseado em tags
• $ref expansão e marcadores de referência circular
• substituição de espaço reservado de caminho com codificação de URL
• truncamento de resposta (maxContextLength)
• ferramentas allowedTools / disallowedTools por fonte
• ApiAuthenticator (bearer / apiKey / custom)
• pular operações @Deprecated

import org.noear.solon.ai.agent.react.ReActAgent;
import org.noear.solon.ai.talents.gateway.OpenApiGatewayTalent;
import org.noear.solon.ai.talents.gateway.openapi.ApiAuthenticator;
import org.noear.solon.ai.talents.gateway.openapi.ApiSource;

import java.time.Duration;
import java.util.Arrays;

OpenApiGatewayTalent apiTalent = new OpenApiGatewayTalent()
        .dynamicThreshold(5)
        .listThreshold(30)
        .searchThreshold(100)
        .maxContextLength(10_000)
        .defaultTimeout(Duration.ofSeconds(30))
        .defaultAuthenticator(ApiAuthenticator.bearer("seu-token"));

// montagem simples de múltiplas fontes
apiTalent.addApi(
Contexto Triplo Up
As empresas brasileiras podem se beneficiar do uso de Gateways para gerenciar suas APIs de forma mais eficiente, reduzindo custos e melhorando a performance dos agentes de IA. A implementação de Talentos Gateway pode facilitar a integração de ferramentas e otimizar processos internos.