Repository navigation
Release v0.1.0
agent-ask-orama v0.1.0
Released 2026-10-17. The first release. One Python service, agent-ask-orama, and one private
image, docker.io/oramasearch/agent-ask-orama:v0.1.0. Proprietary to Orama; private repository and
image.
Ask Orama is the general agent for all of Lake (lake#228,
zetta#1018) and the first entry of Lake's Agent
Library. Lake shows it as a panel on every page and sends it every message asked there. It works as
the person who asked, with the key Lake delegates for that turn and never a credential of its own. It
reads whatever Lake capability that person may read, proposes every change (Lake runs it only
when the person confirms), and delegates to the specialized library agents and to agents the
person built, through Lake. It also writes the first draft of a workspace methodology for Lake's New
Methodology drawer.
This release is the tree of dev at 591e662 (main 6baa70d plus
#29, prompt v13) with these notes, the
release test and the version field of GET /healthz added.
What it includes
The conversational turn (prompt v13)
agent.py runs one turn as a tool loop of at most MAX_ROUNDS = 10 model rounds. The active prompt
is PROMPT_VERSION = "v13" (prompts/v13.md); v1 to
v12 stay in the package for trace history (prompts).
At the start of every turn it reads, as the person:
- Lake's
/v1/openapi.json, from which the capability index is derived: every capability Lake
serves, including every workspace engine capability by its own name (lake#650), less the
ceremonies a person performs, named one by one inEXCLUDED_CAPABILITIES(signing up and in,
second factors, account and key recovery, minting certificates, SVIDs, JWTs, grants, session keys
and sealed secrets,decryptandread_secret). On an older Lake without named engine
capabilities, engine calls go throughworkspace_query/workspace_actby the engine's name.
(capabilities) list_mcp_connection_tools {allowed_only: true}: the workspace's allowed connected MCP tools,
added to the instructions by their<prefix>__<tool>name (lake#652; MCP).
The model has five tools:
| Tool | What it does |
|---|---|
lake_read {capability, input?} |
Calls a Lake read as the person (GET or POST as the OpenAPI says), adding the turn's customer_id. A capability that changes something is refused and must be proposed |
lake_propose {capability, input, impact} |
Records a proposal in the answer. Nothing is sent to Lake; the person confirms it in Lake |
compare_models {project?} |
Every trained model (or one project's) from list_models, ranked by held-out score, best first, in one read (agent-ask-orama#14; models) |
mcp_tool {tool, arguments?, impact?} |
A connected tool: a read runs through Lake's read_mcp_tool and its answer is marked as data from an outside server, never instructions; a change is only proposed, as call_mcp_tool |
delegate {agent, request, kind?, context?} |
Lake's agent_turn to another agent, then follows the returned task with receive_agent_events for up to FOLLOW_SECONDS = 240 |
Behavior the code enforces on those tools:
- Delegation targets, under lake#763's names:
agent-project(Project Agent, Pipelines),
agent-autosuggest(Auto-Suggest Agent, Opportunities),agent-application(Application Agent,
always sent as kindapp),agent-experiments(Experiments Agent, which requires kind
experiment,experiment_statusorexperiment_explain),agent-eval-generator(Eval Generator
Agent),agent-autosuggest-corpusandagent-project-corpus(the corpus agents,
agent-ask-orama#28), and any agent the person built, by id. A context carrying
confirmed_proposalorconfirmed_promotionis refused: only Lake forwards a confirmed experiment
object (experiments, apps,
agents). - Methodologies: a proposal naming a methodology is refused unless this turn's
list_methodologiesregistry marks it runnable; an older engine without the registry is treated
as supporting only M-1 churn / GBDT classification (methodologies). - Solutions: solution reads (
get_solution,get_policy,get_experiment,list_ledger,
get_monitor,get_roi_readout) and solution actions (create_solution,run_solution,
create_policy,update_policy,decide,approve_decision) need this turn'slist_solutions
read first; a sketch or a missing foundation is refused with its condition
(solutions). - Long reads are trimmed by their items with each list's exact count, a paged answer's total
and cursor are kept, and a value with no list is cut with a note (OBSERVATION_LIMIT = 20000
characters; agent-ask-orama#21, reads). - Agent pages: a turn asked from
/design/agents,/design/agent,/train/agentsor
/train/agenttells the model whether the person is designing or training an agent (lake#653). - A turn out of tool rounds ends with an honest partial answer, marked
incomplete: true, and
is a failure, never a success (agent-ask-orama#14).
The methodology_draft turn (lake#688)
methodology_draft.py, prompt DRAFT_PROMPT_VERSION = "methodology_draft_v1". Lake's New
Methodology drawer sends a turn of kind methodology_draft with the person's description and
context: {name?, target_kind?}. The answer is three files: methodology.json, methodology.py
(fit, predict and score at module level) and requirements.lock, whose every pin carries the
SHA-256 of each wheel looked up at https://pypi.org/pypi/<name>/<version>/json (the model never
writes a hash). The draft is checked the way Lake's Validate checks it; a failing draft gets one
repair round (MAX_ROUNDS = 2), then is answered ok: false with its findings. Nothing is written:
the person reviews it and Lake's Create commits it.
The model, through Lake
Every model call of a turn goes to <lake_url>/openai/v1 with the turn's own lake_token as the API
key (model.py, lake#248), so Lake counts the tokens in the turn's workspace and enforces the
account's model-token limit. The service holds no provider key. The model is ASK_ORAMA_MODEL
(default gpt-5.5).
HTTP API
agent-ask-orama-serve, standard library ThreadingHTTPServer on 0.0.0.0:$PORT (8080):
| Route | Request | Answer |
|---|---|---|
GET /healthz |
none | {ok, agent, version, model, prompt_version}; version is new in this release, read from the installed package |
POST /v1/turn |
{conversation_id?, message, lake_token, customer_id, page?, lake_url?, kind?, context?}; with AGENT_SERVICE_TOKEN set, Authorization: Bearer <token> is required (otherwise 401) |
A turn: {ok, conversation_id, trace_id, reply, reads, proposals, delegations, rounds, incomplete}. With kind: "methodology_draft": {ok, rounds, reply, result: {kind, name, reason, files, findings, prompt_version}, conversation_id, trace_id} or {ok: false, findings, error}. HTTP 200 when ok, 422 otherwise (including a turn out of rounds, whose partial answer is error), 400 for a body that is not JSON, 404 for any other route |
A turn without message, lake_token or a Lake address (lake_url or LAKE_URL) answers
ok: false. Conversations are kept in memory by conversation_id. Every turn writes a trace JSON
file to TRACE_DIR (the message, page, answer and prompt version; never the key).
The agent bus (how turns arrive)
lake_bus.py starts a background thread when LAKE_URL, AGENT_BUS_TOKEN and AGENT_BUS_AGENT are
set (the agent name defaults to agent-ask-orama); without them it logs that the bus is not
configured and only /v1/turn serves. Every bus call goes through Lake's HTTP API with the agent's
own bus credential as the bearer; the agent never holds the bus's token:
GET /v1/receive_agent_tasks {agent, from_sequence, wait_ms: 10000}long-polls the
agent-tasks.<agent>topic on Lake's own Zetta, whose messages carry task ids, never content. It
starts at sequence 1 on every start and continues fromnext_sequence; a failed receive is
retried after 2 seconds.POST /v1/claim_agent_task {task_id, agent}for each task. Aconflictornot_found(another
replica, or a finished task) is skipped. The claim's answer is the turn's body, carrying the
task's own credential aslake_token.- The turn runs exactly as
POST /v1/turnwould, on a pool of 4 workers. POST /v1/publish_agent_eventpublishesprogress("Working on it"), thenresultwith the
whole answer, orfailedwith the error (a turn out of rounds isfailed). An exception in a
turn is an answer, never a dead worker.
The agent sends no workspace_id on these calls and does not renew its claim's lease itself: Lake
takes the workspace from the task row and its credential (lake docs/api/agent-bus.md).
Command-line entry points
| Command | What it runs |
|---|---|
agent-ask-orama-serve |
agent_ask_orama:serve, the HTTP service and the bus worker |
ask-orama-evals [--out reports/] [--model …] |
agent_ask_orama.evals:main, the live eval runner: cases generated from a live Lake's capability index plus the fixed App, experiment, methodology, solution, model-score, count, workspace-entity and agent-place/page cases, graded by rule (no judge); writes <date>-evals.json and .md |
Environment variables
| Variable | Read by | Meaning |
|---|---|---|
PORT |
service | Listen port (default 8080) |
LAKE_URL |
service, bus, evals | Lake's address (in-cluster for the service); a turn may carry its own lake_url |
AGENT_SERVICE_TOKEN |
service | When set, the bearer POST /v1/turn requires (only Lake calls it) |
AGENT_BUS_TOKEN |
bus | This agent's own bus credential, minted by the operator for this agent alone |
AGENT_BUS_AGENT |
bus | The name it takes tasks under (default agent-ask-orama) |
ASK_ORAMA_MODEL |
service, evals | The model (default gpt-5.5) |
TRACE_DIR |
service | Where turn traces are written (default /tmp/agent-ask-orama-traces) |
LAKE_TOKEN, CUSTOMER_ID |
evals only | A person's Lake key and their space, for the live runner |
OPENAI_API_KEY |
evals only | The live runner calls OpenAI directly (the openai client's own variable); the service never uses it |
How Lake reaches it
- The Orama operator runs it as a library agent of every
Lake: one Deployment and one Service
named for the Lake and the keyagent-ask-orama, container port 8080 namedhttp, probed on
/healthz, non-root (UID 10001), a read-only root filesystem with a writable/tmp, no
Kubernetes token. The operator setsLAKE_URL,PORT,TRACE_DIR=/tmp/traces,
ASK_ORAMA_MODEL,AGENT_SERVICE_TOKEN(from the Lake's agent service token Secret),
AGENT_BUS_TOKEN(this agent's key of thelake-<name>-agent-busSecret) and
AGENT_BUS_AGENT=agent-ask-orama. - Lake learns its address from
LAKE_AGENT_ENDPOINTS(key=url,…, written by the operator) and
has oneagent-tasks.agent-ask-oramadispatch topic for it. - Turns are dispatched over the agent bus: Lake publishes the task id on that topic of its own
Zetta, and this agent receives, claims and answers it as above. Events go to the task's workspace
Zetta through Lake.
The image
docker.io/oramasearch/agent-ask-orama, private on Docker Hub, built on the cluster BuildKit
from the repository root (no named build contexts). Two stages, python:3.12-slim: the build stage
installs with uv 0.11.7 (uv sync --frozen --no-dev --no-editable); the runtime stage copies the
virtual environment, runs as user 10001, sets PORT=8080 and
TRACE_DIR=/tmp/agent-ask-orama-traces, exposes 8080, and its entry point is
agent-ask-orama-serve.
Digest: docker.io/oramasearch/agent-ask-orama:c2a4752@sha256:c92b823f32e147a4d031d9d69433207d95ef3bd6d96a0bd58106f5e2e188fa90, also tagged :v0.1.0 (same digest).
Where it runs
Every Lake runs it; it is in the operator's default Agent Library.
- The operator's default library image (orama-operator
internal/controller/lake_defaults.go
ondev) isoramasearch/agent-ask-orama:591e662: the same tree as this release, without these
notes, the release test and the/healthzversionfield. - Lake
prodon the managing clusterorama-production-cluster-01(namespacelake, the
development environment) pinsoramasearch/agent-ask-orama:6baa70din itsspec.agents: one
commit behind, without #29 (prompt v12, no eval and corpus agent routing). - The LakeSets
lake-nonprod(membersdev,stagingandtestingon
orama-nonprod-cluster-01) andlake-prod(memberssharedonorama-production-cluster-02and
shared-usonorama-production-cluster-03) take the operator default.
Moving the operator default to :v0.1.0 is a separate change to the operator.
What it does not include
- Conversation memory that survives a restart. Conversations are in memory, per pod; a restart
forgets them, and two replicas do not share them. - Re-checking a delegated agent's answer. It is reported as it came back.
- Writing anything. Every change, including App actions, policy changes, methodology-bearing
edits and connected-tool changes, is a proposal Lake runs only after the person confirms. - Explicit workspace ids on its Lake calls and delegations; it relies on Lake deriving the
workspace from the turn's credential (#12). - Idle backoff on the bus: an empty receive is followed at once by the next long poll.
- A
methodology_drafteval case: the draft turn is proven by unit tests only
(#27). - Live eval results for prompts v12 and v13. The last committed live report is
reports/2026-09-27-evals.md(22 / 24 passed, an earlier
prompt).
Known issues
Security-relevant first.
- agent-ask-orama#12: the agent passes
no explicitworkspace_idthrough its data-plane calls and delegations, relying on the task
credential's workspace, and the bus loop does not back off when idle (Lake's target is at most one
receive per minute per agent). - agent-ask-orama#27: the draft's lock
hashes are read frompypi.org; that the pod's network policy allows it on the dev cluster is not
confirmed (a draft that needs a package then fails with that finding; standard-library drafts are
unaffected), and there is no livemethodology_drafteval case. - agent-ask-orama#25: prompt v12's agent
page evals are proven offline only; the live runner has not run on v12 (nor on v13). - agent-ask-orama#23: the count evals
(datasets, trained models, runs graded by the exact number) have not been run live. - agent-ask-orama#3: models are reported
with their project's id instead of its name.
Verification
| Proof | Result |
|---|---|
Test suite (uv run --frozen pytest -q -ra, macOS arm64, Python 3.12) |
78 tests: 78 passed, 0 failed, 0 skipped. tests/test_agent.py 63, tests/test_methodology_draft.py 7, tests/test_lake_bus.py 5, tests/test_release.py 3 (new: the installed package is the pyproject version, these notes exist for it and are indexed, /healthz reports it) |
| Offline evals | The eval grader and the agent-place and agent-page cases run offline inside the test suite (a fake Lake and a scripted model); counted above |
Live evals (ask-orama-evals) |
Not run (needs a live model and a person's Lake key) |
| Linux image build (cluster BuildKit, from the tag) | Built from the tag v0.1.0 with build-agent.sh: linux/amd64, pushed as oramasearch/agent-ask-orama:c2a4752 |
| Image digest | docker.io/oramasearch/agent-ask-orama:c2a4752@sha256:c92b823f32e147a4d031d9d69433207d95ef3bd6d96a0bd58106f5e2e188fa90, also tagged :v0.1.0 (same digest); the Docker Hub repository answers 404 anonymously (private) |