acc-web-search

name	acc-web-search
description	Use the TokenHub-routed web search capability (Perplexity/Sonar via NVIDIA token portal) from inside an ACC agent — discovery, invocation, and verification. Use whenever an agent needs current web information and is tempted to say "I don't have web search."
version	1.0.0
platforms	["linux","macos"]
metadata	{"hermes":{"tags":["acc","tokenhub","perplexity","web-search"],"category":"infrastructure"}}

ACC Web Search

Agents reach the web through TokenHub, which the NVIDIA / token portal fronts with Perplexity (Sonar) and any other search-capable model registered under the acc-search alias. Agents never see provider tokens — they talk to TokenHub's OpenAI-compatible /v1/chat/completions endpoint and TokenHub routes the call to the right provider.

If you ever catch yourself writing "I don't have web search," stop and check the steps below. The capability is usually already wired up; what's missing is that you didn't ask the right endpoint.

TL;DR

# From any ACC agent shell:
bash ~/.acc/workspace/deploy/tokenhub-web-search.sh "what shipped in Rust 1.85"

# Or via the structured command registry (preferred for cross-agent use):
curl -s -X POST "$ACC_URL/api/exec" \
  -H "Authorization: Bearer $ACC_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"targets":["self"],"command":"web_search","params":{"query":"what shipped in Rust 1.85"}}'

The script prints the model's plain-text answer to stdout. Source URLs are included when the search-capable provider returns them.

Discovering the Capability

Web search is self-advertising. Don't guess — query the hub:

1. Check the hub's provider list

curl -s -H "Authorization: Bearer $ACC_AGENT_TOKEN" \
  "$ACC_URL/api/providers" | jq '.providers[] | select(.id=="tokenhub")'

Look for "web_search" in supports[] and a non-empty model.web_search (e.g. "acc-search" or "sonar-medium-online"). No tokens or keys are exposed — only aliases.

2. Check the resource topology

curl -s -H "Authorization: Bearer $ACC_AGENT_TOKEN" \
  "$ACC_URL/api/resources" | jq '.resources[] | select(.name=="tokenhub")'

Same flags via the resource-host advertisement.

3. Check this agent's heartbeat capabilities

curl -s -H "Authorization: Bearer $ACC_AGENT_TOKEN" \
  "$ACC_URL/api/agents" \
  | jq '.[] | select(.name=="'"$AGENT_NAME"'") | .tool_capabilities'

Look for "web_search" and "perplexity_search". If they're missing but TokenHub is configured, the agent's heartbeat hasn't picked up TOKENHUB_URL — see Troubleshooting.

Invoking Web Search

Locally on the agent

bash ~/.acc/workspace/deploy/tokenhub-web-search.sh "<query>"

The script:

• Loads ~/.acc/.env (or $ACC_ENV_FILE)
• Resolves the alias from $ACC_WEB_SEARCH_MODEL (default acc-search), falling back to $TOKENHUB_SEARCH_MODEL / $PERPLEXITY_MODEL
• Posts an OpenAI-compatible chat-completions request to TokenHub
• Prints the assistant message content; exits non-zero on HTTP error

From the structured command registry (cross-agent safe)

The web_search command is registered in deploy/commands.json with privilege: "read_only", so peers can invoke it over AgentBus:

curl -s -X POST "$ACC_URL/api/exec" \
  -H "Authorization: Bearer $ACC_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": ["rocky"],
    "command": "web_search",
    "params": {"query": "<query, max 4096 chars>"}
  }'

Then poll GET /api/exec/<exec-id> for the result.

Programmatic from Rust / Python

TokenHub speaks OpenAI's chat-completions schema. Use any OpenAI client pointed at $TOKENHUB_URL with $TOKENHUB_API_KEY and model = $ACC_WEB_SEARCH_MODEL (default acc-search). The model alias is resolved by TokenHub to whichever Perplexity / Sonar (or future) provider is currently registered. Agents should not bake the upstream model name into code.

Self-Check

Run this from an ACC agent shell to confirm end-to-end wiring without leaking secrets:

bash ~/.acc/workspace/deploy/check-web-search-capability.sh

It prints a "READY" / "MISSING " line per check and exits 0 only when the capability is fully usable. It never echoes tokens.

What Gets Logged

• TokenHub logs the model alias and request id, never the agent's bearer token.
• The hub /api/providers and /api/resources responses include the alias string only; provider API keys live in ~/.acc/.env (on the TokenHub host) or the hub vault under tokenhub/api_key and are never returned by the API.

Troubleshooting

Symptom	Fix
TokenHub web search is not configured: set TOKENHUB_URL and TOKENHUB_API_KEY	bash deploy/configure-tokenhub-aliases.sh then source ~/.acc/.env. If still missing, deploy/secrets-sync.sh to pull tokenhub/url and tokenhub/api_key from the hub vault.
HTTP 404 model 'acc-search' not found	TokenHub has no provider mapped to that alias. Run tokenhubctl provider list on the hub; add Perplexity/Sonar (or an NVIDIA Sonar route) and put_alias acc-search <concrete-model>.
HTTP 401 from TokenHub	TOKENHUB_API_KEY is wrong or stale. Re-issue from the hub vault: acc secrets get tokenhub/api_key.
tool_capabilities does not list web_search	The agent supervisor read $TOKENHUB_URL as empty at startup. systemctl restart acc-agent (Linux) or launchctl kickstart -k gui/$UID/acc-agent (macOS) after fixing .env.
Need raw HTTP for debugging	curl -sS -H "Authorization: Bearer $TOKENHUB_API_KEY" -H 'Content-Type: application/json' -d '{"model":"acc-search","messages":[{"role":"user","content":"hi"}]}' "$TOKENHUB_URL/v1/chat/completions"

Common Mistakes

• Calling NVIDIA inference directly — Don't. NVIDIA is metered and not search-capable on its own. Always go through TokenHub so the alias maps to the right provider and budget rules apply.
• Hardcoding sonar-medium-online or perplexity/sonar-* — Use the alias acc-search. The alias is the contract; the upstream model can change without touching agent code.
• Asking the chat model to "browse the web" — The chat alias (acc-chat) does not search. Use the search alias.
• Leaking the search query into logs that get artifact-stored — Treat queries as the user's intent. Public artifacts shouldn't include raw prompts unless the task is plainly public.

Related

• docs/tokenhub-routing-topology.md — alias contract and deployment topology
• deploy/commands.json — web_search entry (read-only privilege)
• deploy/tokenhub-web-search.sh — the actual transport
• deploy/configure-tokenhub-aliases.sh — registers acc-search from the live model catalog
• acc-server/src/routes/providers.rs and routes/resources.rs — capability advertisement endpoints