docs: document opencode web-search opt-in + add coder restraint guardrail#64
Merged
Merged
Conversation
…rdrail What enables web search on this stack: setting OPENCODE_ENABLE_EXA=1 and EXA_API_KEY in the deployment env. opencode's built-in `websearch` and `webfetch` tools then activate, and the model picks them up via the standard tool-definition layer (no system-prompt injection needed for awareness — opencode handles it). The opencode subprocess inherits these vars from agentfield's run_cli, so no SWE-AF code is required to turn it on. What's added here: - `.env.example` documents the two env vars - README gets a short "Optional: web search" subsection in Quick Start - `swe_af/tools/web_search.py` exposes one helper, `maybe_apply_coder_guardrail`, that conditionally appends a restraint snippet to run_coder's system prompt when the env vars are set. Why only run_coder: it's the one reasoner with a long iterative loop where a model could plausibly rabbit-hole on searches it could answer by reading the codebase. Other reasoners are short or single-shot — the model's own judgment plus opencode's tool advertisement is sufficient. - 7 unit tests covering env-var gating (both vars required, empty key treated as absent, no append when off, append when on, guardrail text contract). What's NOT added (deliberately): - No "you have web search" prompt boilerplate on every reasoner. opencode already advertises tools to the model via the tool-definition layer — verified by autonomous tool use in a smoke test where the model invoked websearch without being told it had a tool. Adding redundant boilerplate would just eat context. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents how to enable web search on this stack (set
OPENCODE_ENABLE_EXA=1+EXA_API_KEYin the deployment env — that's the whole knob) and adds one targeted prompt-level guardrail onrun_coder.The actual capability is already wired: opencode's built-in
websearch/webfetchactivate when those env vars are set, opencode's subprocess inherits them via agentfield/run_cli, and the model learns about the tools via the standard tool-definition layer (no system-prompt injection from us required for awareness). Verified end-to-end via the agentfield SDK against opencode — the model autonomously invoked Exa Web Search when asked a question that required current information.What's in the diff
.env.example— adds the two env vars with brief docsREADME.md— adds an "Optional: web search" subsection in Quick Startswe_af/tools/web_search.py— single helpermaybe_apply_coder_guardrail(prompt)plus theWEB_SEARCH_CODER_GUARDRAILtext. Helper appends the restraint snippet to a system prompt only when both env vars are set; otherwise returns the prompt unchanged so we don't tell the model about a tool it can't use.run_coderonly — one-line change:system_prompt=maybe_apply_coder_guardrail(CODER_SYSTEM_PROMPT).Why only
run_coderThe coder reasoner runs many turns inside a single coding loop — that's the one place an unrestrained model could rabbit-hole on searches for things it could read from the codebase. Every other reasoner is short / single-shot / analytic, where the model's own judgment plus opencode's tool advertisement is sufficient. Add per-reasoner restraint guidance later only if a specific reasoner is observed over-searching.
What's deliberately NOT added
tools=[...]is silently ignored on opencode/codex/gemini) is a real bug but not blocking web search — opencode enables tools by default, so no allow-list needed for them to function.Tests
7 unit tests on the helper covering env-var gating, the restraint snippet text contract, and edge cases (only one var set, empty string key, non-
1flag value). All sub-second, no API keys required.🤖 Generated with Claude Code