DEV Community: chowyu

AIClaw v1.10.5: Configurable Web Search With Visible Execution Logs

chowyu — Tue, 09 Jun 2026 16:33:40 +0000

AIClaw is a self-hosted AI agent platform, and one of the recurring problems in agent products is how to give an agent fresh web information without turning the whole search path into a black box.

In AIClaw v1.10.5, the project added configurable web search engines and made that flow visible in both agent setup and execution logs. This is a concrete feature in the current repository, not a roadmap idea: the backend added search-engine models, storage, handlers, and a web_search tool implementation, while the web console added a new Search Engine page and agent-side selection for external search.

The problem

There are really two different "web search" cases in agent systems:

The model itself supports built-in search.
The model does not, or you want to route search through your own provider and credentials.

Those are not operationally equivalent. Built-in search is convenient, but external search gives you explicit provider choice, saved credentials, per-agent configuration, and a clearer execution boundary.

AIClaw now supports both modes.

Two search modes in one agent config

The current README describes the behavior clearly:

Built-in mode sends extra_body: {"enable_search": true} to models whose capability profile supports web search.
External mode exposes a web_search tool and routes the call through a selected search engine configuration.

That matters because the agent prompt and runtime behavior stay aligned with the actual path:

In built-in mode, AIClaw records a web_search execution step showing that model-native search was enabled for the LLM request.
In external mode, AIClaw only exposes the web_search tool when that mode is active, and the tool call is resolved through the selected search engine config.

This separation is visible in the current backend code around internal/agent/run.go, internal/agent/prompt.go, and internal/agent/executor.go.

What the new feature actually adds

The feature is broader than "call one API". The repository now includes:

A new search-engine configuration model with provider, name, base_url, api_key, and enabled fields.
Storage and CRUD handlers for search engine configs.
A new web console page for Search Engine management.
Agent form support for choosing built-in vs external web search and binding an enabled search engine.
A web_search tool handler that reads the selected search_engine_id from runtime context.
Tests for request shaping, result normalization, provider-specific behavior, limits, and missing-config handling.

Supported external providers in the current codebase are:

Tavily
SerpAPI
Aliyun IQS

Why this design is useful

The best part of this implementation is that it does not pretend all search is the same.

If your chosen model already supports native search, AIClaw can use that path directly. If you need a controlled external path, AIClaw lets you configure search as a first-class resource and then attach that resource to the agent.

That gives you a few practical advantages:

You can keep provider API keys on the server side instead of pushing them into prompts or ad hoc scripts.
You can save multiple search configs, enable or disable them independently, and test them before using them in a live agent run.
You can see search activity in chat progress and execution logs, including input, output, duration, and errors.
You can keep the agent contract explicit: use built-in search for supported models, or use an external web_search tool with a selected engine.

For teams running local or self-hosted agents, that operational clarity matters more than a generic "AI can browse the web" checkbox.

How the external path works

The current implementation routes external search through a dedicated handler in internal/tools/websearch/search.go.

A few details stand out:

Search requests are rejected if the query is empty.
Disabled configs are not usable for live execution.
Missing API keys fail fast.
Result limits are normalized and capped.
Response size is bounded.
Snippets are cleaned and truncated before being returned to the agent.

Provider handling is explicit rather than abstract hand-waving:

Tavily uses a JSON POST body.
SerpAPI uses query parameters for organic results.
Aliyun IQS uses Bearer authentication and the LiteAdvanced engine.

That kind of provider-specific normalization is exactly what turns a feature from demo-worthy to production-usable.

The web console flow

The UI side is also practical.

The new Search Engine page lets you:

Create multiple configs
Toggle them enabled or disabled
Test saved configs from the list
Test a config directly inside the create/edit dialog before saving

Then, in the agent form, you can:

Enable web search
Choose builtin or external
Select one of the enabled search engines when using external mode

This avoids one common agent-platform failure mode: features exist in backend code, but the operator workflow is awkward enough that nobody uses them correctly.

Observability is the real feature

The technical headline is configurable web search, but the deeper value is observability.

AIClaw does not just say "search happened." It models search as an execution step:

built-in search is recorded as a web_search step attached to the LLM request
external search appears as a tool call with provider-backed results

That makes debugging much easier. When an answer is wrong, you can inspect whether the issue came from:

no search being enabled
the wrong mode being selected
a disabled or missing external config
poor upstream results
or model reasoning after the search results were returned

That is a better operational story than hiding everything behind a generic browse capability.

A practical example

Imagine an AIClaw agent that tracks "latest Go release notes" or "today's AI infrastructure news".

With built-in mode:

choose a model with native search support
enable web search
let AIClaw send enable_search=true

With external mode:

configure Tavily, SerpAPI, or Aliyun IQS in the Search Engine page
enable the config
bind that config to the agent
let the agent call web_search when the question is time-sensitive

In both cases, the execution path is inspectable afterward.

What I like about this release

This feature is a good example of product discipline in an agent codebase:

it added backend data structures
it added runtime wiring
it added UI workflow
it added tests
and it documented the behavioral contract in the README

That is the difference between "we support search" and "operators can actually run this in a controlled way."

If you are building self-hosted agents, configurable web search is not just about freshness. It is about choosing where search happens, how credentials are managed, and how much of the execution trail remains visible after the run.

AIClaw v1.10.5: Configurable Web Search for Tool-Using Agents

chowyu — Tue, 09 Jun 2026 12:00:27 +0000

AIClaw just shipped two updates that make the agent runtime more reliable and more useful for real-world research workflows.

Project: https://github.com/chowyu12/aiclaw

The short version:

v1.10.4 hardens Runtime Plan State so agent plans behave more predictably across tool failures and final message saves.
v1.10.5 adds configurable web search engines, including Tavily, SerpAPI, and Aliyun IQS.

This is a meaningful step for AIClaw because search is no longer treated as a hidden model-side feature only. It can now be configured, tested, observed, and audited as part of the agent runtime.

Why this matters

AI agents often need fresh information: latest releases, pricing, recent policy changes, news, documentation updates, and project status. Previously, this usually depended on either model-native search support or ad hoc browser/web fetch behavior.

AIClaw now supports two web search modes:

Built-in model search
External search engines exposed through a web_search tool

For models that support native web search, AIClaw can send the model request with search enabled. For external search, AIClaw exposes a real tool call and routes it through the selected search engine configuration.

That difference matters. External search becomes visible in execution logs, streams back like other tools, records input/output/duration/errors, and can be managed from the console.

New Search Engine console

The web console now includes a Search Engine page. You can create multiple search configurations and enable or disable them independently.

Supported providers:

Tavily
SerpAPI
Aliyun IQS

The UI supports:

creating and editing search engine configs;
storing provider, base URL, API key, and enabled status;
testing an existing search engine from the list;
testing a new or edited config before saving;
showing whether an API key has been configured without exposing the key value.

For Aliyun IQS, AIClaw calls:

POST https://cloud-iqs.aliyuncs.com/search/unified

with Bearer API key authentication and the LiteAdvanced engine.

Agent-level search mode

Agents now have web search settings in the Agent form.

Each agent can choose:

web search disabled;
built-in search, when the selected model supports it;
external search, using one enabled Search Engine configuration.

If an agent uses external mode, it must select an enabled search engine. Disabled search configs can still be tested from the Search Engine page, but they are not available during live agent execution.

This keeps runtime behavior explicit: the agent does not silently use an unknown search backend.

A real `web_search` tool

AIClaw now includes a built-in web_search tool for external mode. The backend normalizes search requests, limits result count, trims long snippets, and returns structured search results:

{
  "query": "...",
  "provider": "tavily",
  "results": [
    {
      "title": "...",
      "url": "...",
      "snippet": "..."
    }
  ]
}

The implementation includes provider-specific adapters for Tavily, SerpAPI organic results, and Aliyun IQS page items.

Search observability

Search is also part of the execution trace now.

For built-in model search, AIClaw records a web_search execution step showing the search input and request configuration. For external search, the web_search tool call is tracked like other tools, including output, duration, and errors.

That makes search behavior easier to debug. If an answer depends on web results, you can inspect how the search was executed instead of treating it as a black box.

Plan State hardening in v1.10.4

The previous patch release focused on Runtime Plan State reliability.

Key changes include:

stronger validation for plan item states;
duplicate plan item ID rejection;
normalization so only one item can be running;
safer failure transitions when a tool or LLM call fails;
final message linking that completes or fails active plan items correctly;
compact Plan State prompt text truncation to avoid injecting oversized plan fields into the model context.

This matters because AIClaw treats plans as runtime state, not as chat-visible TODO text. The harness owns lifecycle transitions, persistence, streaming, and failure recovery. The new tests make that contract harder to accidentally break.

Tests added

The update adds coverage for:

Tavily search parsing;
SerpAPI search parsing;
Aliyun IQS search parsing;
disabled or missing search engine configuration;
selected search engine routing;
built-in search request configuration;
web_search execution step recording;
plan state normalization, validation, failure handling, and final message linking.

Install or update

AIClaw publishes prebuilt binaries for Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/chowyu12/aiclaw/master/install.sh | bash

Common commands:

aiclaw start
aiclaw stop
aiclaw status
aiclaw update
aiclaw version

What is AIClaw?

AIClaw is a self-hosted AI agent platform for building, operating, and observing tool-using agents. It combines a Go backend, Vue 3 admin console, multi-provider model support, runtime Plan State, tools, skills, sub-agents, memory, and messaging-channel integrations in one deployable binary.

GitHub: https://github.com/chowyu12/aiclaw

If you are working on agent runtime design, tool execution, MCP, Plan State, or observable web search, feedback and issues are very welcome.