anthropic_web_search

Executes server-owned WebSearch tool calls in an Anthropic Messages loop.
On this page

Executes server-owned WebSearch tool calls in an Anthropic Messages loop.

Configuration Notes

Each provider request is executed through the shared filtered-subrequest executor, which enforces destination authority, DNS/SSRF, TLS/SNI, and Host centrally. An optional outbound_chain runs operator-managed cross-cutting filters on the callout; when omitted it defaults to an empty inline chain (pure passthrough), so the central protections still apply.

Configuration

FieldTypeRequiredDescription
providerbrave | tavily | youyesSearch backend provider.
user_credentialstringnoOptional callout-credential slot id. When set, the web-search callout uses the caller’s per-user secret from that slot instead of the shared provider api_key. Non-secret (a slot name). Only valid for header-authenticated providers (Brave, You); rejected for Tavily, which authenticates via the request body.
api_keystring (secret)yesAPI key for the search provider (supports ${ENV_VAR}). Wrapped in [SecretString] to prevent accidental logging.
default_context_sizestringnoDefault search context size when the client omits it.
timeout_msintegernoCallout timeout in milliseconds. Inside an iterative request router, the effective timeout is capped by the router’s remaining deadline.
max_body_bytesintegernoMaximum request body bytes to buffer.
base_urlstringnoOverride the provider’s default API base URL.
outbound_chainstring | objectnoOutbound filter chain the provider callout executes through. A named reference resolves against the top-level filter_chains map, so it binds only when the filter is placed at the top level of a pipeline (see the web-search.yaml example). An inline definition embeds the filters directly and always binds — including when the filter runs nested as a step of an iterative_request_router (the agentic loop), where the step pipeline’s chain map is empty and a named reference cannot resolve. Use an inline chain for any nested/IRR placement; a named reference is available only where top-level filter_chains are in scope. The chain carries cross-cutting concerns (observability, security, credential injection) and is bound once at pipeline-build time — a chain that cannot be built fails config validation. Destination authority, DNS/SSRF, TLS/SNI, and Host are enforced centrally by the executor, gated by insecure_options.allow_private_upstreams. Optional. The provider callout always runs through the shared executor; this chain only adds filters along the way. When omitted it defaults to an empty inline chain (pure passthrough) via [default_outbound_chain], so every central protection still applies. Provide it only to attach cross-cutting concerns.
terminal_streamingboolnoSelect Praxis streaming transport for effective stream: true Messages requests. When enabled, the terminal inference response is streamed incrementally as one coherent client-visible SSE lifecycle while intermediate tool/search transitions stay internal. This knob is anthropic-only; openai_web_search does not accept it.

Examples

Example 1

filter: anthropic_web_search
provider: you
api_key: ${WEB_SEARCH_API_KEY}

Example 2

filter: anthropic_web_search
provider: you
api_key: ${WEB_SEARCH_API_KEY}
outbound_chain: web_search_outbound
default_context_size: medium
timeout_ms: 10000
max_body_bytes: 67108864

Example 3

# cargo run -p praxis-test-utils --example anthropic_messages_web_search_mock
# WEB_SEARCH_API_KEY="$WEB_SEARCH_API_KEY" cargo run -p praxis-ai-proxy -- \
#   -c examples/configs/anthropic/full-flow-agentic.yaml
# curl http://127.0.0.1:8080/v1/messages \
#   -H 'content-type: application/json' \
#   -d '{"model":"openai/gpt-oss-20b","max_tokens":1024,"stream":false,"messages":[{"role":"user","content":"Use web search to look up potato, then summarize in one sentence."}],"tools":[{"name":"WebSearch","description":"Search the web","input_schema":{"type":"object","properties":{"query":{"type":"string"}},"required":["query"]}}]}'