AIClaw, 실행 세부 정보를 숨기지 않는 설정 가능한 웹 검색 기능 추가

대부분의 AI 에이전트 제품들은 "웹 검색"을 할 수 있다고 말하지만, 종종 매우 다른 여러 동작들을 하나의 체크박스로 통합해 버리곤 합니다.

현재 AIClaw 저장소(repository)에서는 웹 검색이 더 명시적으로 모델링되어 있습니다:

일부 모델은 내장된 제공자 측(provider-side) 검색을 사용할 수 있습니다.
다른 에이전트들은 설정된 검색 엔진을 통해 외부 web_search 도구를 호출할 수 있습니다.
두 경로 모두 모호한 마법 뒤에 숨겨지는 대신 런타임 동작에서 확인할 수 있습니다.

이러한 분리는 에이전트를 프로덕션(production) 환경에서 실행하며 비용, 제공자 선택, 프롬프트(prompts), 그리고 감사 가능성(auditability)을 제어하고자 할 때 매우 중요합니다.

AIClaw에서 변경된 사항

최근 AIClaw의 변경 사항으로 전체 검색 엔진 설정 인터페이스와 이를 사용하기 위해 필요한 에이전트 측 배선(wiring)이 추가되었습니다:

웹 콘솔 내 새로운 Search Engine 페이지
백엔드(backend)의 검색 엔진 설정 영속화(persisted)
Tavily, SerpAPI, Aliyun IQS에 대한 외부 검색 지원
builtin 대 external 웹 검색 모드에 대한 에이전트 설정
해당 모드가 선택되었을 때만 모델 네이티브(model-native) 검색을 활성화하는 런타임 처리
외부 엔진이 선택되었을 때 웹 검색을 자동으로 켜주는 후속 UI 수정

이는 단순히 README의 주장만이 아닙니다. 저장소에는 이제 다음이 포함되어 있습니다:

CRUD 및 테스트 엔드포인트를 위한 internal/handler/search_engine.go
제공자별 검색 실행을 위한 internal/tools/websearch/search.go
콘솔 UI를 위한 web/src/views/search-engine/Index.vue
에이전트별 모드 및 엔진 선택을 위한 web/src/views/agent/Form.vue
내장 및 외부 검색 동작을 다루는 테스트

왜 하나의 모드보다 두 개의 검색 모드가 더 나은가

AIClaw는 이제 README.md에 두 가지 별개의 모드를 문서화했습니다:

내장(built-in) 모드: AIClaw는 제공자 네이티브 검색을 지원하는 모델에 대해 extra_body: {"enable_search": true}를 설정합니다.
외부(external) 모드: AIClaw는 web_search 도구를 노출하고 저장된 검색 엔진 설정을 통해 호출을 라우팅합니다.

이 설계는 실제 운영상의 문제를 해결합니다.

제공업체가 이미 검색 기능을 잘 지원하고 있다면 내장형 모델 검색 (Built-in model search)이 편리합니다. AIClaw에서는 프롬프트 레이어 (prompt layer)를 통해 모델에게 최신 정보나 시간에 민감한 질문은 내장 검색을 사용할 수 있음을 명시적으로 알려줍니다. 또한 런타임 (runtime)은 해당 모델 호출에 사용된 요청 설정 (request configuration)을 보여주는 web_search 실행 단계를 기록합니다.

외부 검색 (External search)은 다릅니다. 때로는 검색 동작이 특정 모델 벤더 (model vendor)에 종속되는 것을 원하지 않을 수 있습니다. 때로는 여러 모델 백엔드 (model backends)에 걸쳐 검색 제공업체를 표준화하고 싶을 수도 있습니다. 때로는 제공업체를 교체하거나, 독립적으로 테스트하거나, 혹은 구조화된 입출력을 가진 일반적인 도구 호출 (tool call)로서 검색을 가시적으로 유지하고 싶을 수도 있습니다.

AIClaw는 하나의 타협안을 강요하는 대신 이러한 분리를 지원합니다.

워크플로우 작동 방식

사용자 워크플로우는 간단합니다:

AIClaw 관리 콘솔에서 Search Engine 페이지를 엽니다.
하나 이상의 검색 설정 (search configs)을 생성합니다.
제공업체 (provider)를 선택합니다: Tavily, SerpAPI, 또는 Aliyun IQS.
API 키와 선택 사항인 베이스 URL (base URL)을 저장합니다.
실제 사용 전에 설정을 테스트합니다.
에이전트 (agent)를 엽니다.
웹 검색 (web search)을 활성화합니다.
도구 기반 검색을 원하는 경우 external 모드를 선택합니다.
해당 에이전트에 대해 활성화된 검색 엔진 중 하나를 선택합니다.

백엔드에서 AIClaw는 실제 활성화된 검색 엔진이 선택되었을 때만 외부 모드 (external mode)가 수락되도록 검증합니다. 해당 검증 로직은 internal/handler/agent.go 내부의 validateExternalWebSearch에 구현되어 있습니다.

프론트엔드의 후속 수정 사항 또한 중요합니다. web/src/views/agent/Form.vue에서 이제 외부 모드를 선택하면 가능한 경우 첫 번째 활성화된 엔진이 자동으로 선택되며, 엔진을 선택하면 웹 검색이 자동으로 활성화됩니다. 이는 사소해 보일 수 있지만, "엔진을 선택했는데 왜 검색이 여전히 꺼져 있지?"와 같은 흔한 설정 실수 (footgun)를 방지해 줍니다.

제공업체 동작은 대충 처리되지 않고 구현되었습니다

AIClaw는 외부 검색을 일반적인 프록시 블롭 (proxy blob)으로 취급하지 않습니다. 이 리포지토리(repository)에는 명시적인 제공업체(provider) 로직이 포함되어 있습니다:

Tavily는 https://api.tavily.com/search를 사용합니다.
SerpAPI는 https://serpapi.com/search.json을 사용합니다.
Aliyun IQS는 https://cloud-iqs.aliyuncs.com/search/unified를 사용합니다.

이 도구는 제한 사항을 정규화(normalize)하고, 설정 상태를 검증하며, 너무 큰 스니펫 (snippet)을 다듬고, 제목(title), URL, 스니펫 필드를 포함한 구조화된 결과(structured results)를 반환합니다.

즉, 운영자는 자신의 환경에 적합한 엔진을 선택하면서도, 에이전트(agent)는 제공업체와 관계없이 예측 가능한 형식으로 웹 검색 결과를 사용할 수 있음을 의미합니다.

관찰 가능성 (Observability) 부분이 진정한 강점입니다

제가 가장 좋아하는 부분은 AIClaw가 검색 동작을 관찰 가능하게 (observable) 유지한다는 점입니다.

내장 검색 (built-in search)의 경우, 런타임 (runtime)은 모델 네이티브 검색이 활성화되었음을 기록하고 web_search 단계에 요청 설정 (request configuration)을 저장합니다.

외부 검색 (external search)의 경우, 에이전트는 일반적인 web_search 도구 경로를 사용하므로 도구 입력 (input), 출력 (output), 지속 시간 (duration) 및 오류 (errors)가 채팅 진행 상황과 실행 로그에 그대로 표시됩니다.

이는 AIClaw의 더 넓은 설계 방향과 일치합니다. 런타임 계획 상태 (plan state), 생성된 파일, 실행 단계, 메모리, 그리고 이제는 검색 동작까지도 숨겨진 구현 세부 사항이 아닌 일급 런타임 객체 (first-class runtime objects)로 취급됩니다.

실제 업무를 위해 에이전트를 운영하고 있다면, 이는 블랙박스 형태의 "웹 브라우징" 토글보다 더 나은 트레이드오프 (tradeoff)입니다.

실질적인 예시

두 가지 에이전트를 가정해 보겠습니다:

강력한 내장 검색 지원을 가진 모델을 사용하는 뉴스 모니터링 에이전트
특정 외부 검색 제공업체를 반드시 사용해야 하는 리서치 또는 컴플라이언스 (compliance) 에이전트

AIClaw에서 이들은 동일한 검색 경로를 사용할 필요가 없습니다.

첫 번째 에이전트는 더 긴밀하게 통합된 제공업체 경험을 위해 내장 모드 (built-in mode)를 유지할 수 있습니다.

두 번째 에이전트는 외부 모드 (external mode)로 전환하여 선택한 엔진에 바인딩(bind)할 수 있으며, 검색 동작을 검사 가능한 결과가 포함된 도구 호출 (tool call)로서 가시적으로 유지할 수 있습니다.

이는 모든 검색 유스케이스 (use case)가 동일한 척하는 것보다 더 프로덕션 친화적인 (production-friendly) 모델입니다.

이 기능이 눈에 띈 이유

제가 이 주제를 선택한 이유는 백엔드(backend), 런타임(runtime), 테스트(tests), 그리고 UI에 걸쳐 최근 구현의 깊이가 있는 구체적인 기능이기 때문입니다:

기능 커밋(feature commit): 설정 가능한 검색 엔진 (configurable search engines)
후속 수정(follow-up fix): 엔진이 선택되는 즉시 외부 검색이 활성화됨
README에 문서화된 동작 (documented behavior)
내장 실행(built-in) 대 외부 실행(external execution)에 대한 명시적 테스트

이러한 조합은 AIClaw가 어떻게 진화하고 있는지를 보여주는 좋은 사례입니다. 단순히 또 다른 기능을 추가하는 것이 아니라, 그 기능을 설정 가능하고(configurable) 조사 가능하게(inspectable) 만들고 있습니다.

AIClaw는 오픈 소스(open source)이며 셀프 호스팅(self-hosted) 방식이므로, 이러한 세부 사항들이 중요합니다. 스택(stack)을 직접 제어할 때는 에이전트(agent)가 외부 세계에 접속하는 방식 또한 제어할 수 있어야 합니다.