Repository navigation
Release v0.1.0
agent-creator v0.1.0
Released 2026-10-17. The first release. One private image, docker.io/oramasearch/agent-creator:v0.1.0.
It carries the Agent Creator Agent (AgentCreator), the agent behind lake's Agent Factory
(Design → Agents: Describe it to the Agent Factory). A person describes the agent they want; it
reads their workspace, then asks one question, declines work the workspace engine cannot run, or
proposes the agent in Studio's shape: native or Python, and for Python whether its code is stored in
Zetta or in a lake repository. It creates nothing: lake shows the proposal and creates the agent
only when the person approves it (lake#233). Proprietary to Orama; private repository and image.
It is not a program of its own. It is a definition (definition/) that runs on
agent-runtime; the image is the runtime plus the
definition. This release is the same tree as commit 6b1cc36, the commit Lake already runs, plus
these notes, the release test and the README and docs index lines that point at them.
What it includes
The definition
| File | What it is |
|---|---|
definition/record.json |
Its agent record: id agent-creator, name AgentCreator, kind orama, work area workspace, skills search and summarize, model gpt-5.5 |
definition/agent.toml |
Entrypoint agent.main:run, model gpt-5.5, dependency openai; no tools allow-list, so the runtime's derived tools are not narrowed further |
definition/instructions.md |
The prompt, prompt v5 (the version is the file's first heading; there is no constant in code) |
definition/agent/main.py |
The turn: read the workspace, call the model, check the answer with defects, one repair round, then answer |
What one turn does (agent.main:run)
- Reads the workspace, live, every turn (nothing is cached between turns), through the tools
agent-runtime derives for the person who sent the turn:- solutions:
list_solutions, thenget_solutionfor every returned id. An older engine's
unknown_capabilitymeans the solution registry is not deployed; there is no fallback solution; - Apps and builds:
list_apps,get_app,receive_app_events(from sequence 1, no wait) for
each App, andlist_builds,get_build,receive_build_eventsfor each build, each only when
the runtime granted those reads for this turn. App and build calls carry the turn's
customer_id; - methodologies:
list_methodologies. An older engine'sunknown_capabilityswitches to the
documented compatibility contract: only M-1 (churn / GBDT classification) runs; - datasets:
list_datasets; - Pipelines:
list_projects, thenget_projectfor each project; only graphs with
approval: approvedwhose methodology (if any) is runnable are offered for grants, the others
are listed as not runnable.
- solutions:
- Calls the model (
context.client, which agent-runtime points at lake's model gateway with the
turn's own key) with the prompt, the workspace facts and the conversation so far, asking for a
JSON object. - Checks the answer by rule (
defects). An answer is aquestion, adecline(naming a
methodology or a solution, with its tracking issue) or aproposal. A proposal is rejected when:- its type is not
nativeorpython, or the agent has no name; - it grants a skill outside agent-runtime's twelve:
search,generate-data,train,
summarize,call-api,drives,transcripts,repositories,datasets,streams,
pipelines,usage(agent-runtime#7); - its work area is not
workspace,projectordataset; - a methodology it records is not in this turn's registry or not runnable, or it trains without
recording one; - an App agent is not Python, reads outside the turn's App grant, subscribes to a topic other
than a liveapp-events.<app-id>, a livebuild-events.<build-id>orbuild-events.*,
proposes an App or build change outside the grant, does not delegate changes to
agent-applicationwith turn kindapp, or itsagent.tomltoolsdiffer from its reads plus
proposals; - a solution binding names a solution that is not in this turn's registry, is a sketch or is not
runnable; its capabilities are not exactlydecide,list_ledger,get_monitor,
get_roi_readout; its autonomy differs from the solution's autonomy defaults; or an A1 action
class is not approval-gated; - a Pipeline grant is not an approved, runnable Pipeline of this workspace, or its methodology is
not recorded; - a native agent carries code or a trigger;
- a file path leaves the definition; Python does not compile or imports something outside the
standard-library list and the runtime's packages (openai,httpx,pydantic,pandas,
numpy);agent.tomlasks for other dependencies; something looks like a secret; - a Python agent is not stored in
zettaorlake, or is stored inzettawith more than 900 KiB
of code.
- its type is not
- One repair round: a defective answer goes back to the model once with its defects. A second
defective answer is returned with its defects, never as clean. - Answers
{"reply": <one sentence for a person>, "result": {kind, question | decline | proposal, defects, facts}}(agent-creator#1).
How it is served (agent-runtime's service mode)
The Dockerfile sets AGENT_MODE=service, AGENT_PER_TURN_CREDENTIALS=1 and
AGENT_DEFINITION_DIR=/definition. In that mode agent-runtime:
- serves HTTP on
PORT(8080):GET /healthz:{ok, agent, name, tools, model};POST /v1/turn: a JSON body withmessage(orrequest),conversation_id,lake_token,
customer_id, and optionallyworkspace_id,pageandlake_url. WhenAGENT_SERVICE_TOKEN
is set, the request must carryAuthorization: Bearer <that token>. The answer is
{ok, conversation_id, trace_id, reply, result, calls, rounds, finished, proposals}:200when
it answered,422when the turn failed,400for a body that is not JSON or has no message,
401without the token;
- works per turn: each turn's
lake_tokenandcustomer_id(both required) are the person's
delegated credential; the tools are derived from lake's OpenAPI for that credential, so it reads
only what the person may read, and the model is called through lake's gateway with that key; - keeps each conversation's messages in the pod's memory, keyed by
conversation_id; - writes a trace per turn under
TRACE_DIR.
This repository adds no HTTP route and no version endpoint; the runtime owns HTTP.
How Lake reaches it
-
The Orama operator runs it as a library agent: one Deployment (one replica) and one Service
per Lake, port 8080 namedhttp, startup, readiness and liveness probes on/healthz, user 10001. The operator gives the pod
LAKE_URL(lake's in-cluster address),AGENT_SERVICE_TOKEN,AGENT_BUS_TOKEN(its own bus
credential) andAGENT_BUS_AGENT=agent-creator. -
Lake learns its address from
LAKE_AGENT_ENDPOINTS(agent-creator=<url>, among the other
library agents), and presentsLAKE_AGENT_SERVICE_TOKENas the bearer. -
Turns arrive over the agent bus (lake
docs/api/agent-bus.md, lake#269). Lake publishes each
task id onagent-tasks.agent-creatoron lake's Zetta (task ids only, never content). The
runtime's bus client (agent_runtime.lake_bus, started only whenAGENT_PER_TURN_CREDENTIALS=1
andLAKE_URL,AGENT_BUS_TOKENandAGENT_BUS_AGENTare all set):- long-polls
receive_agent_tasks(10-second wait) from sequence 1 at start; - calls
claim_agent_taskfor each task; aconflictornot_foundmeans another replica won;
the claim answers the turn body with the task'slat.credential in it; - runs up to four turns at once; for each it publishes one
progressevent (Working on it),
runs the same turn handler as/v1/turn, then publishesresult(the whole answer) or
failed.
It sends no further progress events during a turn; Lake renews the lease on each capability call
made with the task credential. - long-polls
CLI entry points
None of its own (package = false, no [project.scripts]). The image's entrypoint is
agent-runtime's agent-runtime. evals/run.py is the eval runner (below).
Environment variables
Read by the definition: none. Set by the Dockerfile: AGENT_DEFINITION_DIR, AGENT_MODE,
AGENT_PER_TURN_CREDENTIALS, TRACE_DIR. Read by agent-runtime in this mode:
| Variable | Meaning |
|---|---|
LAKE_URL |
lake's address, for turns, the model gateway and the bus |
AGENT_SERVICE_TOKEN |
the bearer /v1/turn requires, when set |
AGENT_BUS_TOKEN, AGENT_BUS_AGENT |
its bus credential and the agent key it takes tasks under |
AGENT_MODEL |
the model when the record names none (the record names gpt-5.5) |
PORT |
the HTTP port (8080) |
TRACE_DIR |
where turn traces are written (the operator sets /tmp/traces) |
AGENT_DEFINITION_DIR, AGENT_MODE, AGENT_PER_TURN_CREDENTIALS |
the built-in definition and the mode |
Read by evals/run.py: LAKE_URL, LAKE_TOKEN (a person's token), CUSTOMER_ID, AGENT_MODEL, and
the OpenAI client's own OPENAI_API_KEY.
Evals and tests
evals/run.py: asks generated from the skills × work areas × with or without code, plus live
App/build, methodology and solution cases, run against a real workspace and graded by rule
(defectsplus case facts; no judge). Reports land inreports/; the one recorded run is
reports/2026-09-27-evals.md, 15/16 with prompt v1. No report exists for prompt v3 or v5.tests/test_creator.py: 25 tests with a fake workspace and scripted model replies.tests/test_release.py: the release test (below).
Contracts: Apps and builds, methodologies,
solutions.
The image
docker.io/oramasearch/agent-creator, private on Docker Hub. The Dockerfile is
FROM docker.io/oramasearch/agent-runtime:${RUNTIME_TAG} plus COPY definition /definition and the
four environment variables above. It needs no named build contexts; RUNTIME_TAG is a build
argument. It inherits the runtime's user (10001), port 8080 and entrypoint. The v0.1.0 image is
built on agent-runtime v0.1.0
(RUNTIME_TAG=f3ebbe4, the runtime's release commit;
oramasearch/agent-runtime:v0.1.0@sha256:f14cbc7b7f82d3a9bb54635011d9b5daf019cd89c41e38dce7b00185e297e73f),
so its GET /healthz reports the runtime's version.
Where it runs
Every Lake runs it. The operator's default library image (orama-operator
internal/controller/lake_defaults.go on dev) is oramasearch/agent-creator:6b1cc36-f8feb14
(this repository at 6b1cc36 on agent-runtime f8feb14).
- Lake
prodon the managing clusterorama-production-cluster-01(namespacelake; the
development environment) pinsoramasearch/agent-creator:6b1cc36-f8feb14in itsspec.agents. - LakeSet
lake-nonprod(membersdev,staging,testingonorama-nonprod-cluster-01) and
LakeSetlake-prod(memberssharedonorama-production-cluster-02,shared-uson
orama-production-cluster-03) take the operator default.
v0.1.0 is the same definition as that running commit, on agent-runtime v0.1.0 instead of f8feb14
(the same runtime code plus its release notes and the version field on /healthz). Moving the operator default (and Lake
prod's pin) to :v0.1.0 is a separate operator change.
What it does not include
- It creates nothing. Creating the approved agent, and the check job that first runs it, are
lake's (lake#233). - It does not change existing agents: the Factory only proposes new ones (lake#271).
- It proposes only what the twelve skills can do. An agent that needs a new kind of access needs
a new skill in agent-runtime first. - It checks that Python compiles, not that it does the right thing.
- No live eval of the current prompt. The only recorded eval is prompt v1 (15/16); prompt v5 needs
a Lake with the twelve skills deployed (lake#650). - Conversation memory is per pod and in memory. A pod restart loses the earlier messages of every
conversation; the runtime does not read lake'sprior_turnfield.
Known issues
Security-relevant first.
- Workspace identity is not passed explicitly on every call
(agent-creator#9, with
agent-runtime#6): App and build reads
carry onlycustomer_id, the bus client takes noworkspace_id, and the idle bus poll runs every
10 seconds rather than at most once a minute. Lake's task credential still cannot select another
workspace. list_methodologiesis not one of its tools. Its record grantssearchandsummarize, and
onlytrainandpipelinesgrantlist_methodologies. Deployed, the read fails with
'list_methodologies' is not one of this agent's tools, so the methodology registry is
unavailablefor every turn: methodology-bound proposals and declines fail their checks, and
approved Pipelines that name a methodology are offered as not runnable. The unit tests do not see
it because their fake workspace answers every read. agent-creator#11.- The structured answer is shipped, the issue is still open
(agent-creator#1):replyis now words
andresultcarries the structure; the issue stays open for lake's side to readresult. - Lake's documentation describes a narrower turn key than this agent uses: lake's
docs/api/agent-launches.mdsays the Agent Creator Agent is handed a turn key limited to
workspace_query/workspace_openapi, while the definition calls solution, App, build, dataset
and project capabilities directly. Which one holds is decided by lake, and is not proven live for
this release.
Verification
| Proof | Result |
|---|---|
Test suite (uv run --frozen pytest -q -ra, macOS arm64, Python 3.12) |
26 passed, 0 failed, 0 skipped: tests/test_creator.py (25), tests/test_release.py (1) |
| Offline evals | None: every eval case runs against a live workspace |
Live evals (evals/run.py) |
Not run (needs a live model and a live workspace) |
| Linux image build (cluster BuildKit, from the tag) | Built from the tag v0.1.0 with build-agent.sh with AGENT_BUILD_ARGS="RUNTIME_TAG=f3ebbe4" (agent-runtime v0.1.0): linux/amd64, pushed as oramasearch/agent-creator:64dfaa6-f3ebbe4 |
| Image digest | docker.io/oramasearch/agent-creator:64dfaa6-f3ebbe4@sha256:238a84cd60799f76775683c16840834367e79db63e7abe352950c34da694762a, also tagged :v0.1.0 (same digest); the Docker Hub repository answers 404 anonymously (private) |