Files
zeekayandHanzo Dev bcb27958ec agent: every Responses-API agent gets the web — search, fetch, deep research
The builtin registry held five TIME tools. An agent on /v1/responses asking to
search the web had nothing to call, while /v1/websearch/search, /v1/crawl and
/v1/ask had been live the whole time. The capability existed and no agent could
reach it.

Three tools, registered unconditionally so an agent's tool list does not change
shape with deployment:

  web_search     ranked hits with titles, URLs, snippets
  fetch_url      pages as clean Markdown (this module's own crawl)
  deep_research  a cited report synthesised across sources

EVERY BACKEND IS A SEAM, and that is forced rather than chosen.
agent/builtin_tool/web must stay a LEAF: `object` imports `agent`, `agent`
imports the registry, so a tool reaching into object for Crawl closes the loop —
agent → builtin_tool → web → object → agent — and the module stops compiling.
Search and research are the HOST's anyway (hanzoai/cloud serves them and imports
this module, so it cannot be imported back). Crawl is installed by this module's
bootstrap; the host installs the other two at mount time, beside the balance and
tier readers it already installs.

That shape is also the lesson this repo already paid for: the ai module once
reached its own platform over api.hanzo.ai, which carries a CUSTOMER credential
and answers 401 to a service, and every completion fail-closed at 503 on a
healthy pod. The edge is for customers; in-process is for us.

AN UNAVAILABLE CAPABILITY IS AN ERROR, NEVER AN EMPTY RESULT — the property
worth the most here. A model reads ordinary tool text as a FINDING: hand it "no
results" when the backend was never installed and it concludes the web holds
nothing on the subject, then answers from memory in a confident voice. That is a
fabricated answer caused by a deployment gap, and nothing downstream can tell it
from a real one. A genuinely empty search still returns a normal result, because
that IS a finding.

Bounded on purpose: limit clamped to 10 (a confused call must not exhaust the
agent's context window), 5 URLs per fetch, 20k markdown per page, and a failed
page is NAMED rather than omitted — an agent cannot tell "unreachable" from
"said nothing" if it silently disappears.

fetch_url accepts only absolute http(s). The URLs it is handed come from PAGES
the model read, so following file:// or a custom scheme would read the host's own
disk on behalf of whoever wrote that page. It also accepts a bare string, which
is the shape a model sends most often and is unambiguous.

13 tests, including the refuse-vs-empty property for all three tools, the scheme
filter, the clamps, and that the tools are both REGISTERED and exposed in
GetToolsAsProtocolTools — a tool absent from that list is invisible to agents
however well it is registered.

Co-authored-by: Hanzo Dev <[email protected]>
2026-08-05 01:38:04 -07:00

114 lines
3.6 KiB
Go

// Copyright 2023-2025 Hanzo AI Inc. All Rights Reserved.
// Portions Copyright 2025 The OpenAgent Authors. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package builtin_tool
import (
"context"
"encoding/json"
"github.com/ThinkInAIXYZ/go-mcp/protocol"
"github.com/hanzoai/ai/agent/builtin_tool/time"
webtools "github.com/hanzoai/ai/agent/builtin_tool/web"
)
type BuiltinTool interface {
GetName() string
GetDescription() string
GetInputSchema() interface{}
Execute(ctx context.Context, arguments map[string]interface{}) (*protocol.CallToolResult, error)
}
type ToolRegistry struct {
tools map[string]BuiltinTool
}
func NewToolRegistry() *ToolRegistry {
registry := &ToolRegistry{
tools: make(map[string]BuiltinTool),
}
registry.RegisterTool(&timetools.CurrentTimeTool{}) // get current time
registry.RegisterTool(&timetools.LocalTimeToTimestampTool{}) // local time to timestamp
registry.RegisterTool(&timetools.TimestampToLocalTimeTool{}) // timestamp to local time
registry.RegisterTool(&timetools.TimezoneConversionTool{}) // timezone conversion
registry.RegisterTool(&timetools.WeekdayTool{}) // weekday calculator
// The web. Registered unconditionally: a tool is DECLARED here and its backend
// is installed by the host, so an agent's tool list does not change shape with
// deployment. A capability the host did not install answers that it is
// unavailable rather than returning nothing — an agent told "no results" would
// conclude the web is empty on the subject and answer from memory instead.
registry.RegisterTool(&webtools.SearchTool{}) // web_search
registry.RegisterTool(&webtools.FetchTool{}) // fetch_url (native crawl)
registry.RegisterTool(&webtools.ResearchTool{}) // deep_research
return registry
}
func (r *ToolRegistry) RegisterTool(tool BuiltinTool) {
r.tools[tool.GetName()] = tool
}
func (r *ToolRegistry) GetTool(name string) (BuiltinTool, bool) {
tool, exists := r.tools[name]
return tool, exists
}
func (r *ToolRegistry) GetAllTools() map[string]BuiltinTool {
return r.tools
}
func (r *ToolRegistry) GetToolsAsProtocolTools() []*protocol.Tool {
var tools []*protocol.Tool
for _, tool := range r.tools {
// InputSchema to protocol.InputSchema
schemaInterface := tool.GetInputSchema()
schemaBytes, err := json.Marshal(schemaInterface)
if err != nil {
continue // 跳过无法序列化的工具
}
var inputSchema protocol.InputSchema
if err := json.Unmarshal(schemaBytes, &inputSchema); err != nil {
continue // 跳过无法反序列化的工具
}
tools = append(tools, &protocol.Tool{
Name: tool.GetName(),
Description: tool.GetDescription(),
InputSchema: inputSchema,
})
}
return tools
}
func (r *ToolRegistry) ExecuteTool(ctx context.Context, name string, arguments map[string]interface{}) (*protocol.CallToolResult, error) {
tool, exists := r.GetTool(name)
if !exists {
return &protocol.CallToolResult{
IsError: true,
Content: []protocol.Content{
&protocol.TextContent{
Type: "text",
Text: "Tool not found: " + name,
},
},
}, nil
}
return tool.Execute(ctx, arguments)
}