에이전트가 한 번에 80개의 도구 (tools)를 볼 수 있다고 해서 모델이 더 똑똑해지는 것은 아닙니다. 오히려 더 노이즈가 심해집니다. 토큰 비용은 치솟고, 도구 선택 (tool choice)은 표류하며, 단순한 "주문 상태 확인" 프롬프트가 갑자기 회사 전체 OpenAPI 인터페이스의 절반을 차지하게 됩니다.

Solon AI (v4.0.3)는 solon-ai-talent-gateway에 포함된 Gateway Talent 트리오를 통해 이 문제에 답합니다:

세 가지 모두 동일한 4단계 적응형 탐색 (four-stage adaptive discovery) 모델을 공유합니다. 작은 카탈로그는 완전히 확장된 상태를 유지합니다. 대규모 카탈로그는 요약(summary) → 이름 목록(name list) → 검색(search) 단계로 접혀서, LLM이 꼭 필요한 부분에 대해서만 비용을 지불하게 합니다.

이 기사는 article/1353, article/1389, article/1335, article/1293의 공식 API를 기반으로 합니다.

게이트웨이가 "단순한 도구"가 아닌 Talent인 이유

Solon AI에서 **도구 (Tool)**는 원자적 함수 (atomic function)입니다. Talent는 도구들을 지침 (instruction), 활성화 (activation), 그리고 SOP 스타일의 제약 조건과 함께 패키징합니다.

게이트웨이에는 이러한 패키징이 필요합니다:

• 너무 많은 원시 스키마 (raw schemas)는 컨텍스트 (context)를 폭발시킵니다.
• 서로 다른 시스템의 도구들은 그룹화와 생명주기 (lifecycle) 관리가 필요합니다.
• 모델은 첫 번째 턴에서 모든 것을 삼키는 것이 아니라, 단계별로 능력을 탐색해야 합니다.

이것이 바로 모든 OpenAPI 연산을 defaultToolAdd에 쏟아붓는 대신, defaultTalentAdd(...) (또는 요청 범위의 talentAdd)를 통해 게이트웨이를 연결해야 하는 이유입니다.

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

MCP 기능에는 solon-ai-mcp도 필요합니다. OpenAPI 파싱에는 swagger-parser (v2 및 v3)가 포함됩니다. 문서를 전혀 로드하지 않을 경우에만 이를 제외하십시오.

4단계 (세 가지 게이트웨이 공통)

문서의 설계 규칙: 카탈로그(catalog)가 작을 때는 모델이 한 번에 호출할 수 있도록 지시문(instruction)에 전체 스키마를 포함시키고, 규모가 커지면 정보를 접어서(fold) 점진적인 발견(progressive discovery)을 강제합니다.

공통 설정값 (Shared knobs):

1. OpenApiGatewayTalent — Swagger를 에이전트 인터페이스로 변환

도구가 이미 OpenAPI / Swagger 문서(원격 http:// 또는 로컬 classpath:)로 존재하는 경우에 사용하십시오.

공식적으로 명시된 기능:

• Swagger 2.0 + OpenAPI 3.0 자동 감지 (auto detection)
• 태그 기반 그룹화(tag-based grouping)를 통한 다중 소스 로드 (multi-source load)
• $ref 확장 및 순환 참조(circular-ref) 마커
• URL 인코딩을 통한 경로 플레이스홀더(path placeholder) 교체
• 응답 절단 (maxContextLength)
• 소스별 allowedTools / disallowedTools 설정
• ApiAuthenticator (bearer / apiKey / custom)
• @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;
...

단계별 내장 OpenAPI 프록시 도구:

인증 우선순위: 소스 인증기 (source authenticator) > defaultAuthenticator.

런타임 권한 수정은 ApiSourceClient 복사본에서 수행된 후, refreshApi(...)를 통해 적용됩니다:

var client = apiTalent.getApiSource("http://pay-service:8083/v3/api-docs");
client.setAllowedTools(Arrays.asList("createPayment"));
client.getDisallowedTools().add("queryRefund");
...

2. ToolGatewayTalent — 로컬(및 혼합) FunctionTools 관리

도구가 코드 내에 존재할 때 — AbsToolProvider, 단일 FunctionTool, 또는 이미 가져온 MCP 도구 등 — 그리고 도구의 세밀한 단위(granularity)로 런타임(runtime)의 명령형(imperative) 추가/제거가 필요할 때 사용합니다.

import org.noear.solon.ai.talents.gateway.ToolGatewayTalent;

ToolGatewayTalent toolGateway = new ToolGatewayTalent()
...

내장된 프록시 도구(proxy tools):

문서의 중요한 FULL 모드 관련 참고 사항: 기존 비즈니스 도구들은 LLM에 직접(directly) 노출됩니다. 프록시 3인방(proxy trio)은 카탈로그가 FULL 모드를 벗어난 후에만 나타납니다.

3. McpGatewayTalent — 여러 MCP 서버, 하나의 에이전트

도구가 MCP 서비스로 제공되며, 런타임에 모든 도구를 일일이 선택하는 대신 연결(connections) 관리(선택적 허용/차단 목록 포함)를 선호할 때 사용합니다.

import org.noear.solon.ai.mcp.client.McpServerParameters;
import org.noear.solon.ai.talents.gateway.McpGatewayTalent;

...

기억해둘 만한 공식 라이프사이클(lifecycle) 상세 내용:

• refresh는 섀도 스왑(shadow swap)(새 도구를 추가한 후 기존 도구를 제거) 방식을 사용하여, 진행 중인 호출(in-flight calls)이 빈 도구 테이블을 보지 않도록 합니다.
• removeMcpServer는 기저의 연결(underlying connection)을 닫습니다.
• McpClientProvider.setEnabled(false)를 통한 비활성화는 도구 인덱스만 제거합니다. 프로바이더(provider)는 다시 활성화 및 refresh를 호출할 때까지 살아 있습니다.

프록시 도구 이름은 ToolGatewayTalent와 일치합니다: call_tool / get_tool_detail / search_tools.

적절한 게이트웨이 선택 (및 흔한 MCP 혼동)

**유입 형태(ingress shape)**와 **변경 단위(mutation unit)**에 따라 선택하세요:

흔한 실수: “도구별로 MCP 제어가 필요하므로, 반드시 ToolGatewayTalent를 사용해야 한다.”

그럴 필요 없습니다. McpGatewayTalent는 이미 McpServerParameters의 allowedTools / disallowedTools를 통해 도구 수준의 노출을 지원합니다. 목록을 변경한 후에는 refreshMcpServer(...)를 호출하십시오.

실제 구분:

• ToolGatewayTalent = 런타임(runtime), 명령형(imperative), 단일 도구 변형(single-tool mutations)
• McpGatewayTalent = 연결 생명주기(connection lifecycle) + 연결/새로고침 시점의 선언적 허용/거부(declarative allow/deny)

소스가 서로 다른 경우, 동일한 에이전트에 하나 이상의 게이트웨이 Talent를 장착할 수도 있습니다.

공식 노트의 프로덕션 체크리스트 (Production checklist)

1. 소스 전반에 걸친 고유한 도구/작업 이름 — 소문자로 저장되며, 호출 시 대소문자를 구분하지 않습니다.
2. 경로 파라미터(Path params)는 반드시 {name} 형식을 사용해야 함 — 게이트웨이가 교체될 값을 URL 인코딩합니다. 남겨진 {xxx}는 명확한 오류를 발생시킵니다.
3. 사용 중단된(Deprecated) OpenAPI 작업은 자동으로 건너뜁니다.
4. 비활성화된 소스 (ApiSource.setEnabled(false) / 프로바이더 setEnabled(false))는 관리를 위해 등록된 상태로 유지되지만, 다시 활성화 및 새로고침하기 전까지는 도구 인덱스에서 제외됩니다.
5. 권한 수정 시 새로고침 필요 — 클라이언트 복사본에서 허용/거부(allow/deny)를 변경하는 것만으로는 충분하지 않습니다.
6. 임계값(Thresholds)은 제품 결정 사항임 — 전체 스키마(FULL schemas)가 이미 컨텍스트를 점유하고 있다면 dynamicThreshold를 조기에 낮추십시오. 카탈로그가 매우 작고 정밀한 원샷 호출(one-shot calls)이 중요한 경우에만 임계값을 높이십시오.

최소한의 “언제 일반 도구(plain tools)를 떠나야 하는가?” 규칙

도구 세트가 작고 항상 관련성이 있는 동안에는 AbsToolProvider + @ToolMapping + defaultToolAdd 방식을 유지하십시오.

다음 중 하나라도 해당되면 게이트웨이 Talent로 전환하십시오:

• 여러 서비스로부터 오는 수십 개의 OpenAPI 작업(operations)
• 매 턴마다 전체 스키마를 쏟아내지 않아야 하는 MCP 서버
• 크기가 변하는 런타임 플러그인 스타일의 도구 카탈로그
• “모두 보여주기” 대신 점진적 발견(progressive discovery)이 필요한 경우

게이트웨이는 ReAct 계획(planning), 인간 개입(HITL), 또는 세션 메모리(session memory)를 대체하지 않습니다. 게이트웨이는 더 좁고 고통스러운 문제, 즉 도구 표면(tool surfaces)이 확장됨에 따라 사용 가능한 상태를 유지하는 문제를 해결합니다.

공식 참조 (Official references)

공식 참조 (Official references)

• Gateway trio + four stages: https://solon.noear.org/article/1353
• Maven 모듈 solon-ai-talent-gateway: https://solon.noear.org/article/1389
• Tool vs Talent: https://solon.noear.org/article/1335
• ReActAgent 설정 / talents 필드: https://solon.noear.org/article/1293
• ReAct 호출 옵션: https://solon.noear.org/article/1347
• MCP 클라이언트 기본 사항: https://solon.noear.org/article/993

본 문서 작성에 사용된 Solon 버전: v4.0.3.