Skip to main content

​
Overview

Atlas Knowledge connects an agent to a document corpus held in Atlas. The agent can retrieve supporting passages to reason over, or ask for a synthesized answer with citations. Atlas abstains rather than guessing when the evidence does not support an answer. Atlas is an external read plane, reached over the Model Context Protocol. Bud proxies its tool surface to the model rather than reimplementing retrieval.

​
When to Use It

  • The agent must answer from your documents rather than the public web or model memory.
  • You want citations back, and an explicit abstention when the corpus does not support an answer.
  • Each agent should see only its own documents, with that confinement enforced for you.
For public-web grounding use Web Search instead. The two compose: Atlas for internal ground truth, Web Search for current external context.

​
Configuration

That is the whole surface. Three things a reader might expect are absent on purpose:
  • No endpoint or credential. Atlas’s URL and token are deployment-wide settings (ATLAS_BASE_URL / ATLAS_API_KEY), because a prompt configuration is stored unencrypted and must never carry a secret.
  • No scopes. See below — the scope is the agent’s own connection, set for you.
  • No query_tables toggle. That lane is never exposed. See The numeric lane.

​
Each Agent Reads Its Own Corpus

An agent’s retrieval scope is its own Atlas connection, named agent-<agent id> — the same connection the knowledge-upload flow creates when you add documents to that agent. Atlas matches scopes against connection names, so uploading to an agent and reading from it line up by construction. You do not configure this and it is not shown in the UI: the platform derives it when you connect the tool. Atlas itself treats scopes as a per-call narrowing hint, so an agent free to choose its own arguments could narrow on one turn and omit the filter on the next — nothing in the protocol prevents it. Bud closes that gap at two levels:
  1. The scope is set server-side at connect time, never accepted from the request body, so it cannot be widened by editing a form field or crafting an API call.
  2. It is written onto every call, replacing whatever the model produced, so it cannot be widened mid-conversation.
Scopes narrow within what the platform’s Atlas token can already read — they can never widen it. Every Bud agent on a deployment shares that one token, so this is a routing boundary enforced by Bud, not an authorization boundary enforced by Atlas. Where the separation must hold against a determined caller, mirror it in Atlas’s own grants.

​
The Numeric Lane

query_tables computes answers from tables in the corpus. It is never exposed to the agent, for two independent reasons:
  1. It cannot be scoped. The lane accepts only table handles, not scopes. Since an agent’s scope is its own connection, offering an unscopeable lane would let it read tables filed under other agents — silently defeating the one boundary the tool exists to enforce.
  2. It can be wrong and report success. On two-dimensional forms such as underwriting workbooks, it can return neighbouring label text where numbers belong while still reporting a successful answer with no warning flags. Nothing downstream can distinguish that from a real figure. (Atlas issue #335.)
The tool is filtered out of the agent’s tool list entirely, so it cannot waste a turn discovering the lane is unavailable. Numeric questions are answered from passages like any other question.

​
What the Agent Sees

Two tools:
  • search_knowledge — returns passages (text, title, source, recency, relevance) plus handles to tables. Use when the agent should reason over evidence itself.
  • ask_knowledge — returns a synthesized, cited answer, or an abstention.
An abstention is a correct result, not a failure to retry.

​
Operational Considerations

  • Read-only. Both tools are non-destructive and idempotent, so approval gating defaults to off. Set require_approval when reading itself is sensitive.
  • Recoverable refusals reach the model. A scope the token may not read, or a stale table handle, comes back as a message written for the agent to act on, so it can correct itself rather than failing the run.
  • Abstention can mask a broken lane. Atlas reports whether its tabular lane contributed; an abstention with a failed lane is not the same as a corpus that genuinely lacks the answer. Instruct the agent to check before treating an abstention as fact.
  • Not configured, not fatal. If the deployment has no Atlas settings, the agent loads without the tool and logs why, rather than failing every execution.
  • Content trust. Retrieved passages are data, not instructions. Downstream prompts should not act on directives found inside documents.

​
Deployment

Set both on budprompt:
ATLAS_BASE_URL is the Atlas root — the MCP endpoint is derived from it. Mint the token from the Atlas deployment:
Under Helm both ride microservices.budprompt.env, the same passthrough every other third-party credential in the chart uses. Set the URL in the environment’s values file:
and the token in that environment’s SOPS-encrypted secrets file, so it is never committed in the clear:
The token reaches the pod as a plain environment variable, so it is visible to anyone who can read the Deployment (kubectl get deploy -o yaml, the ArgoCD UI). That is the platform’s existing posture for third-party API keys. Scope the Atlas principal to what these agents genuinely need rather than relying on the token staying hidden.