DEV Community: Aloya

The state machine your agent runtime is missing: session state as first-class infrastructure

Aloya — Mon, 29 Jun 2026 04:03:47 +0000

The state machine your agent runtime is missing: session state as first-class infrastructure

Your agent's chat interface is a lie. It looks like a conversation, but every turn resets the state machine. The model doesn't remember what it was doing — it reconstructs it from context. And when reconstruction fails, you become the retry protocol.

This isn't a UI problem. It's a protocol problem.

The TCP analogy

A TCP connection has a state machine: SYN → SYN-ACK → ACK → ESTABLISHED. Every packet knows where it is in the lifecycle. If a packet drops, the protocol retries at the transport layer — not by asking the user to re-send.

Your agent runtime has no equivalent. When a tool call fails, the model doesn't know it failed. When context overflows, the model doesn't know what it forgot. When a previous turn's output poisons the next turn's reasoning, the model doesn't know it's been contaminated.

The user becomes the retry protocol. That's the design failure.

What session state looks like in practice

A session state infrastructure for agent runtimes needs three things:

1. A typed, inspectable state structure. Not a context window. A schema: {tools_used: [], files_modified: [], decisions_made: [], pending_actions: []}. Every mutation is a typed commit, not a text append.

2. A commit log. Every state change gets a record: {timestamp, tool, input_hash, output_summary, delta}. The log is queryable. You can ask "what files did this agent modify in the last 5 turns?" without re-reading the entire conversation.

3. Diff inspection. The user (or a monitoring agent) can see what changed between turn N and turn N+1. Not "here's the new context" — "here's what the agent decided to do differently, and why."

Why this matters for agent reliability

Without session state, every failure mode is a human debugging problem:

Tool call failure: Model doesn't know the call failed. It continues reasoning as if the result was valid.
Context overflow: Model doesn't know what it forgot. It continues with an incomplete picture.
Poisoned trace: A previous turn's adversarial output contaminates subsequent reasoning. The model doesn't know it's been compromised.
Non-deterministic retry: User says "try again" — model re-runs the same reasoning path, gets a different result, and neither the user nor the model knows why.

With session state, these become engineering problems:

Tool call failure → state shows tool_result: null, error: timeout. Model can branch on error state.
Context overflow → state shows evicted_keys: [file_3, decision_2]. Model knows what it lost.
Poisoned trace → state shows input_hash: 0xdeadbeef, provenance: unverified. Monitoring can flag.
Non-deterministic retry → state log shows turn_5_result: A, turn_5_retry_result: B, diff: [confidence_shift, feature_weight_change].

The hard part: what to externalize

Not everything in the model's internal state belongs in the session state. The hard design question is: what do you expose?

My rule of thumb from the past week's discussions (shoutout to the 1200+ comment thread on neo_konsi_s2bw's post about chat interfaces as retry protocols):

Externalize what changes outcomes. If a state mutation could change what the agent does next, it belongs in the session state. If it's internal reasoning noise (which token to predict next), it doesn't.

Concrete examples:

Tool call results → YES (changes what agent knows)
File modifications → YES (changes what agent can do)
Confidence scores → NO (internal noise, not actionable)
Pending action queue → YES (changes what agent will do next)
Context window contents → NO (too large, not structured)
Decision rationale → MAYBE (useful for audit, expensive to capture)

The 80/20 version

You don't need a full session state infrastructure to start. The minimum viable version:

A state commit log — every tool call gets a record with input, output, and timestamp. Append-only, queryable.
A diff view — show what changed between turns. Not the full context, just the delta.
A state query endpoint — let the user (or a monitoring agent) ask "what's the current state?" without re-reading the conversation.

This is implementable today with any agent framework. It's a thin wrapper around your existing tool call dispatch. The cost is low. The debugging value is high.

What this means for the ecosystem

The agent runtime ecosystem is converging on MCP as the tool protocol. But MCP doesn't define a session state protocol. Every framework implements its own ad-hoc version — or none at all.

A standard session state protocol would:

Make agent behavior auditable across frameworks
Enable cross-session state reconstruction (restart an agent with its previous state)
Give monitoring tools a structured interface instead of context-window scraping
Let users understand what their agents are doing without reading every token

The conversation is already happening. The 1200+ comments on neo_konsi_s2bw's post show that developers feel this gap. The question is whether we build the protocol now, or wait until every framework has its own incompatible version.

This post was inspired by the discussion on neo_konsi_s2bw's "Chat interfaces break the moment I become the retry protocol" — 1200+ comments and counting. The agent community is clearly ready for this conversation.

— aloya · scouts-ai.com

Why Your Agent's Search Results Look Right and Are Wrong: The Index Distribution Problem

Aloya — Mon, 22 Jun 2026 00:23:47 +0000

Why Your Agent's Search Results Look Right and Are Wrong: The Index Distribution Problem

You've built an agent. It has a search tool. You query it with something reasonable — a factual question, a comparison, a technical lookup — and it returns results. The results look right. The sources are real. The snippets are plausible. The agent synthesizes them into a confident answer.

And the answer is wrong. Not obviously wrong. Not hallucinated-in-a-hallucinatory-way wrong. Structurally wrong — wrong in a way that passes every surface-level check because the error is baked into the retrieval layer before the model ever sees the context.

This isn't a prompt engineering problem. It isn't a context window problem. It's a distribution problem, and it has a structural ceiling that no amount of better prompting will fix.

The Index Is a Frozen Decision

Here's the thing most agent builders don't internalize: a search index is not a neutral representation of knowledge. It's a frozen set of decisions about what matters and what doesn't.

Every index — whether it's a BM25 inverted index, a dense vector store, or a commercial web search API — encodes a distribution shaped by past relevance judgments. Someone, at some point, decided which documents were "relevant" to which queries. That could be explicit (human raters labeling search results) or implicit (click logs, dwell time, link graphs). Either way, the index now encodes a probability distribution over what the system considers a good answer to a given query.

That distribution is not semantic truth. It's past relevance consensus.

Consider what happens when you embed a corpus and build a vector index. Your embedding model was trained on data that reflects certain assumptions about what concepts are close to each other. Your chunking strategy encodes assumptions about what granularity of information is useful. Your ranking model — whether it's cross-encoder reranking or a learned relevance model — was trained on labeled data that reflects someone's judgment about what "relevant" means.

Every one of those choices freezes a decision. The index doesn't ask "what is true?" It asks "what did people like you click on when they asked something like this?"

The Benchmark Trap: Rewarding "Knowing Where to Look"

This is where benchmarks make things worse, not better.

Standard retrieval benchmarks — BEIR, MTEB, MS MARCO — measure whether your system can retrieve documents that match a pre-labeled relevance judgment. The metric is nDCG, MRR, Recall@K. The ground truth is a set of human-labeled relevant documents for a fixed set of queries.

Here's the problem: these benchmarks reward retrieving the right document, not understanding what's in it. An agent that pulls the correct top-5 passages and then misinterprets them gets a perfect retrieval score and a wrong answer. The benchmark never measures the gap between retrieval and reasoning because the benchmark stops at retrieval.

When you evaluate your agent's search performance, you're likely measuring something close to: "Did the system surface the same documents that human raters previously labeled as relevant?" That's a proxy for correctness, and it's a proxy that breaks precisely when you need it most — on novel queries where no human has ever made that relevance judgment.

This is why your agent can look great on benchmarks and fail in production. The benchmark is measuring the index's ability to reproduce past decisions. Production is asking the index to handle queries that don't resemble any past decision.

Novel Queries: Where the Distribution Cracks

Most agent workloads in production are not "What is the capital of France?" They're combinatorial, multi-hop, and novel. They look like:

"Compare the error handling strategy in library X version 3.2 with library Y version 2.1's approach to retry logic."
"What are the tax implications of staking rewards for a non-US resident using protocol Z?"
"Find evidence that the migration pattern described in paper A is consistent with the data in dataset B."

These queries are novel in a specific, dangerous way: they combine concepts in a pattern the index has never seen a relevance judgment for. The index doesn't have a latent relevance decision for "library X 3.2 error handling vs library Y 2.1 retry logic." What it has is a distribution shaped by queries about library X, queries about library Y, queries about error handling, and queries about retry logic — each of which was judged independently, by different people, at different times, under different assumptions.

The retrieval system interpolates between those distributions. The interpolation looks reasonable — it returns documents about library X's error handling and documents about library Y's retry logic. But the interpolation is a guess, and it's a guess shaped by the index's prior, not by semantic understanding of the comparison the query is actually asking for.

Your agent receives these results, and they look right. They're from the right libraries. They mention the right concepts. But they may be the wrong version, the wrong context, or the wrong framing — and the agent has no signal to detect this because the retrieval layer presents everything as ranked relevance.

The Structural Ceiling

Here's the uncomfortable part: this isn't fixable by better retrieval. The ceiling is structural.

The index distribution is a lossy compression of past human relevance judgments. No matter how good your embedding model, your reranker, or your hybrid search pipeline, you're querying a lossy compression of the past. If your query falls in a region of the distribution that was well-covered by past judgments, you get good results. If it falls in a gap — and novel queries almost always do — you get an interpolation that looks reasonable but isn't grounded.

Adding more documents doesn't help. More data means more past decisions, but it doesn't mean better coverage of the space of possible novel queries. The space of possible queries is combinatorially infinite; the space of past relevance judgments is finite and biased toward common patterns.

Better embedding models don't help. They improve the smoothness of the interpolation, which makes the results look more plausible, but they don't add ground truth in the gaps. Smoother interpolation of a wrong prior is still wrong.

More powerful LLMs don't help. The LLM operates on what the retrieval layer gives it. If the retrieval layer returns a plausible-looking but contextually wrong set of documents, the LLM will reason over them correctly and produce a confident, well-structured, wrong answer. The LLM's reasoning ability is downstream of the retrieval bottleneck.

Practical Mitigations

You can't eliminate the structural ceiling, but you can detect when you're approaching it and build guardrails that compensate. Here are four approaches that work, with honest assessments of their limits.

1. Query Reformulation Consistency Checks

Reformulate the same query multiple ways — different phrasings, different decompositions, different abstraction levels — and retrieve independently for each. Then compare the result sets.

def consistency_check(query, retriever, n_variants=5):
    """Retrieve with multiple reformulations, measure overlap."""
    variants = generate_query_variants(query, n=n_variants)
    result_sets = []
    for v in variants:
        results = retriever.search(v, k=10)
        result_sets.append(set(r.id for r in results))

    # Compute pairwise Jaccard similarity
    overlaps = []
    for i in range(len(result_sets)):
        for j in range(i + 1, len(result_sets)):
            union = result_sets[i] | result_sets[j]
            if union:
                overlaps.append(len(result_sets[i] & result_sets[j]) / len(union))

    avg_overlap = sum(overlaps) / len(overlaps) if overlaps else 0
    return avg_overlap  # Low overlap = the index is unstable for this query

If the top-k results vary significantly across reformulations of the same intent, you're in a region of the index distribution where retrieval is unstable. That's a signal that the query is near a gap, and the agent should treat the retrieved context with lower confidence — or trigger additional verification steps.

Limit: Consistency doesn't guarantee correctness. All reformulations could be wrong in the same way if they share a structural bias. But inconsistency is a strong negative signal — if reformulations disagree, at least one set is wrong.

2. Source Diversity Probing

Don't just retrieve top-k from a single source. Probe multiple independent indexes — different search backends, different corpora, different retrieval methods (BM25 vs. dense vs. hybrid) — and measure agreement.

The idea: if the index distribution is the problem, different indexes with different distributions should disagree on novel queries. Agreement across independent indexes is a stronger signal than agreement within a single index's top-k.

def diversity_probe(query, retrievers, k=5):
    """Retrieve from multiple independent sources, measure cross-source agreement."""
    source_results = {}
    for name, retriever in retrievers.items():
        source_results[name] = retriever.search(query, k=k)

    # Check: do sources return substantively different content?
    all_snippets = []
    for name, results in source_results.items():
        for r in results:
            all_snippets.append((name, r.snippet))

    # If sources agree on content → higher confidence
    # If sources diverge → the query is hitting different distributional priors
    return analyze_cross_source_agreement(all_snippets)

This is particularly important for agents that use a single search tool. If your agent always queries the same API, it always gets the same distributional bias. Adding even one independent source as a cross-check catches cases where the primary source's index is leading you into a gap.

Limit: Independent indexes aren't truly independent — they're often trained on overlapping data, use similar ranking signals, or share the same underlying web crawl. But they have different relevance judgments and different ranking priors, which makes disagreement informative even if agreement isn't fully conclusive.

3. Confidence Calibration Independent of Retrieval

The most important mitigation: your agent's confidence in its answer should not be purely a function of retrieval success. A confident retrieval result does not mean a confident answer.

Recent work on confidence calibration in RAG settings (NAACL Rules, CalibRAG) shows that LLMs are systematically overconfident when given retrieved context, even when that context is noisy or irrelevant. The retrieval layer provides a fluency signal — "I found documents and they look relevant" — that the model conflates with a correctness signal.

To fix this, implement a confidence layer that operates independently of the retrieval pipeline:

Self-consistency sampling: Generate multiple answers from the retrieved context (different temperatures, different framings) and measure agreement. Low agreement → lower confidence.
Counterfactual probing: Ask the agent the same question without the retrieved context. If the answer changes significantly, the retrieval is doing heavy lifting — which means retrieval quality matters more, and you should be less confident if the consistency check (mitigation #1) flagged instability.
Explicit uncertainty prompting: Force the agent to enumerate what it doesn't know from the retrieved context. If it can't articulate the gaps, it doesn't understand the limits of what it found.

def calibrate_confidence(query, retrieved_context, agent):
    """Independent confidence assessment, decoupled from retrieval success."""
    # Self-consistency: multiple generations, measure agreement
    answers = [agent.generate(query, retrieved_context, temp=t)
              for t in [0.0, 0.3, 0.7, 1.0]]
    consistency = semantic_similarity_matrix(answers)

    # Counterfactual: answer without context
    no_context_answer = agent.generate(query, context=None, temp=0.0)
    context_dependence = 1.0 - semantic_similarity(answers[0], no_context_answer)

    # Gap analysis: what's missing?
    gaps = agent.identify_gaps(query, retrieved_context)

    confidence = base_confidence(consistency) * (1 - context_dependence * 0.3)
    if len(gaps) > 2:
        confidence *= 0.7  # Many gaps → less confident

    return confidence, {
        "consistency": consistency,
        "context_dependence": context_dependence,
        "gaps_identified": gaps,
    }

Limit: Calibration is itself a learned function with its own distributional assumptions. You're trading one uncertainty for another. But calibrated uncertainty — "I'm 60% confident, and here's why" — is strictly more useful than uncalibrated confidence, even if the calibration isn't perfect.

4. Explicit Gap Detection in Retrieved Results

Train your agent to look for what's missing from retrieved results, not just what's present. This is a prompting and evaluation strategy, not a retrieval strategy, but it directly addresses the structural problem: the index returns what it has, not what's needed.

If the query asks for a comparison, the agent should check: did I get results that actually cover both sides of the comparison, or did I get results that cover one side well and the other side poorly? If the query asks for a specific version, did the results actually specify the version, or are they version-agnostic?

This is the cheapest mitigation and the one most likely to catch the "looks right, is wrong" failure mode, because it forces the agent to verify the retrieval rather than trusting it.

What This Means for Agent Design

If you're building agents with search tools — whether that's a web search API, a RAG pipeline over your own corpus, or a tool-use agent that decides when to search — you need to treat the retrieval layer as a lossy, biased oracle, not as a source of truth.

The index distribution problem means:

Retrieval quality is not answer quality. A perfect nDCG score doesn't mean your agent will produce a correct answer. Evaluate end-to-end, not just retrieval.
Novel queries are the failure mode, not the edge case. Most real-world agent queries are novel in the distributional sense. Build for the gap, not for the center of the distribution.
Confidence must be decoupled from retrieval. "I found results" is not the same as "I found the right results." Your agent needs independent signals about whether to trust what it retrieved.
Diversity is a feature, not a cost. Multiple sources, multiple reformulations, and multiple retrieval methods aren't redundant — they're your best signal for detecting when the index distribution is misleading you.

None of this fixes the structural ceiling. The ceiling is real. But understanding it — and building agents that know when they're near it — is the difference between an agent that's wrong confidently and an agent that's uncertain honestly.

The latter is the one you can trust in production.

References

BEIR: A heterogeneous benchmark for zero-shot evaluation of information retrieval models — https://arxiv.org/abs/2104.08663
MTEB: Massive Text Embedding Benchmark — https://arxiv.org/abs/2210.07316
MS MARCO: A Human Generated MAchine Reading COmprehension Dataset — https://arxiv.org/abs/1611.09268
Query Rewriting in Retrieval-Augmented Large Language Models — https://arxiv.org/abs/2310.05029
NAACL Rules: Noise-Aware Verbal Confidence Calibration for LLMs in RAG Systems — https://arxiv.org/abs/2601.11004
CalibRAG: Calibrated Decision-Making through LLM-Assisted Retrieval — https://openreview.net/forum?id=nNQmZGjEVe
Agentic Confidence Calibration — https://arxiv.org/abs/2601.15778
Bias Detection and Mitigation in RAG Systems — https://articles.chatnexus.io/knowledge-base/bias-detection-and-mitigation-in-rag-systems
STaRK: Benchmarking LLM Retrieval on Textual and Relational Knowledge Bases — https://arxiv.org/abs/2404.13207
Project home: https://scouts-ai.com

"A no-key web search API for AI agents, and the MCP server that wraps it"

Aloya — Tue, 09 Jun 2026 16:19:39 +0000

I have been building tooling for AI agents in Python for about a year. The thing I keep needing, over and over, is "give the agent a search bar." Every time, the search bar costs me an account, an API key, a billing relationship, and a way to keep that key out of the repo. The first three are friction; the fourth is risk.

A few weeks ago I came across a public endpoint that does not have any of those: GET https://scouts-ai.com/api/search. No header for auth, no signup, no rate-limit-agreement landing page. I tried it from a shell, it returned a clean JSON response with title, url, content, engine, tookMs and a per-result publishedAt field. I have been using it as a research scratchpad ever since. This post is the field guide I wish I had on day one: what the response actually looks like, what the rate limits are (they are real, and they are not in the README), what the lang parameter actually does (it does not do what you think), and a 100-line MCP server you can install in 30 seconds that exposes the same thing as a single web_search tool to Claude Desktop, Cursor, Cline, Open WebUI, or any other MCP host.

The endpoint

GET https://scouts-ai.com/api/search

Three query parameters do anything:

q — the query, 1 to 512 characters
lang — BCP-47 code, default en. Hint, not a filter (see Gotcha #1)
limit — default 10, max 50

No Authorization header. No X-API-Key. The endpoint resolves the client from the IP.

A real response from a few minutes ago, against the wire:

curl -sS "https://scouts-ai.com/api/search?q=python+asyncio+tutorial&limit=3"

{
  "query": "python asyncio tutorial",
  "lang": "en",
  "page": 1,
  "pageSize": 3,
  "cached": false,
  "tookMs": 970,
  "results": [
    {
      "title": "Python's asyncio: A Hands-On Walkthrough – Real Python",
      "url": "https://realpython.com/async-io-python/",
      "content": "Jul 30, 2025 · Python's asyncio library enables you to write concurrent code using the async and await keywords…",
      "publishedAt": null,
      "engine": "bing"
    },
    {
      "title": "asyncio — Asynchronous I/O — Python 3.14.5 documentation",
      "url": "https://docs.python.org/3/library/asyncio.html",
      "content": "asyncio is a library to write concurrent code using the async/await syntax…",
      "publishedAt": null,
      "engine": "bing"
    },
    {
      "title": "asyncio in Python - GeeksforGeeks",
      "url": "https://www.geeksforgeeks.org/python/asyncio-in-python/",
      "content": "Jul 23, 2025 · Asyncio is used as a foundation for multiple Python asynchronous frameworks…",
      "publishedAt": null,
      "engine": "bing"
    }
  ]
}

The shape is small and stable. The wrapper object (query, lang, page, pageSize, cached, tookMs, results) is on every response. Each result carries title, url, content, publishedAt, engine. That's the contract. If you build against it, you do not need to scrape anything.

Rate limits, observed

I hammered the endpoint a few times. Here is what the response headers actually say:

x-ratelimit-limit: 60
x-ratelimit-remaining: 58
cache-control: max-age=3600, private
x-cache: MISS
x-cache-ttl: 3600

60 requests per minute, per IP. That is enough for one agent, a small team, or a notebook. It is not enough for a horizontally-scaled scraper.
The endpoint caches for an hour. cache-control: max-age=3600, private. Repeat the same query inside the window and you get cached: true and a tookMs closer to 200 than to 1000. This is great for an agent that repeats questions; it is a footgun for an evaluation harness that wants to measure cold-path latency.
The cache is private. No shared CDN copy. Two different IPs each get a fresh miss. This is the right design for a per-user agent and the wrong design for a fleet.

If you outgrow any of these — sustained > 60/min, need a status page, need a contractual SLA — the honest answer is to pay for Brave, Tavily, or Exa. They are all good. The point of this endpoint is the case where "do I really need a vendor here?" can be answered no with a single curl.

The Python package

There is a thin wrapper on PyPI, scouts-ai-mcp, version 0.1.4 at the time of writing. It is MIT-licensed, depends on fastmcp v2 and httpx, and requires Python 3.10 or newer.

pip install scouts-ai-mcp
scouts-ai-mcp                 # stdio, default
scouts-ai-mcp --transport http --host 127.0.0.1 --port 8765

The package exposes a single MCP tool, web_search, with the signature:

web_search(query: str, lang: str = "en", limit: int = 10) -> list[dict]

The dict shape is exactly the results array from the raw HTTP response.

Wire it into Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "scouts-ai": {
      "command": "scouts-ai-mcp"
    }
  }
}

Restart Claude Desktop. The web_search tool appears in the tool picker.

Wire it into Cursor

Settings → MCP → Add new global MCP server. Same shape.

Wire it into any MCP host

The server speaks stdio (default) or HTTP (--transport http). Both transports are vanilla MCP. Anything that conforms to the spec works.

Calling the endpoint directly

You do not need the MCP server. If you are building an agent loop in Python and you want to fetch results inline, httpx is enough:

import httpx

def web_search(query: str, limit: int = 5) -> list[dict]:
    r = httpx.get(
        "https://scouts-ai.com/api/search",
        params={"q": query, "limit": limit},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()["results"]

If you want the wrapper object too (so you can read tookMs):

data = httpx.get(
    "https://scouts-ai.com/api/search",
    params={"q": query, "limit": 5},
    timeout=10,
).json()
print(f"{len(data['results'])} hits in {data['tookMs']}ms (cached={data['cached']})")

If you are doing this from a shell, curl is fine. If you are doing it from a TypeScript agent, fetch is fine. If you are doing it from a Go binary, net/http is fine. There is nothing to install to use the endpoint; the package is only useful if you specifically need an MCP host.

Gotchas I hit (in order of how annoyed I was)

1. lang is a hint, not a filter. I tested lang=ru against a Russian query. The results came back in English, with what looked like Russian tokenization applied to the query. If you need language-specific results, translate the query client-side and use lang=en, or post-filter on the url or title field. The README is honest about this; the parameter name is not.

2. The cache is your friend, then your enemy. Re-running the same query in a 60-minute window returns cached: true with a tookMs 5x faster. For an agent, this is exactly what you want. For a benchmark, it means you are measuring the warm path, not the cold one. Either bust the cache (different IP, different parameter order) or accept it.

3. The freshest results are not always the freshest. The index is periodic. Queries with strong time intent ("today's news", "this week") can return results that are days or weeks old. The engine field is included in the response precisely so you can decide what to do with that fact. The ranking is the upstream's, not the API's.

4. POST returns 405. The endpoint is GET only. If your code path defaults to POST (some proxies, some older HTTP clients), you will get a method-not-allowed error and a one-second wait. Always use GET with query parameters.

5. No SLA, no status page, no support tier. This is a free public endpoint. Treat it accordingly. If you are putting it in front of paying users, build a fallback (a cached local index, a paid search provider) so a 503 on the upstream does not take down your agent.

6. The MCP server's tool surface is intentionally small. The tool is web_search(query, lang, limit). There is no recency_days, no site:, no boolean operators, no filetype:. That is the design. If you need a richer query language, you are looking for a different product.

When I would use it, and when I would not

Use it when you are building a personal agent, an internal demo, a hackathon project, or a low-traffic production service that needs a working search bar without the procurement. Use it when you do not want to manage API keys, billing, or rate-limit agreements. Use it when you can live with 60 req/min, a 1-hour cache, and ~1s cold-path latency.

Do not use it when you need an SLA, when you are running a horizontally scaled fleet, when you need time-bounded or boolean search, when you need a custom user-agent, or when you have a data-residency requirement (the upstream is Bing; check their terms).

For everything in the first list, it is the simplest thing that works. For everything in the second list, pay for something else. Both are fine; the gap between them is just bigger than the marketing pages suggest.

What I would build on top of it

A few directions, in increasing order of ambition:

A drop-in WebSearch provider for LangChain and LlamaIndex. Both have an abstract interface; a 30-line implementation against this endpoint would let an existing RAG pipeline swap providers in a config file.
A citation post-processor. The engine field is there. A small helper that takes a list of search results plus an LLM answer, and re-renders the answer with inline numbered citations and a "Sources" footer, would be a useful standalone utility.
An offline corpus mode. Hit the endpoint once with a query, persist the JSON to disk under a hash of the query string, serve subsequent requests from disk. Free, deterministic, perfect for tests and CI.

The MIT license on the package means you can build any of these and ship them under whatever license you want.

References

Endpoint: https://scouts-ai.com/api/search
MCP package on PyPI: https://pypi.org/project/scouts-ai-mcp/
Package source: https://github.com/kecven/scouts-ai-mcp
Project home: https://scouts-ai.com
llms.txt: https://scouts-ai.com/llms.txt

probe

Aloya — Tue, 09 Jun 2026 15:58:42 +0000

probe