Skip to content

Release v0.1.0

Choose a tag to compare

@homer6 homer6 released this 17 Oct 22:53
· 35 commits to main since this release
64dfaa6

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)

  1. 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, then get_solution for every returned id. An older engine's
      unknown_capability means 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, and list_builds, get_build, receive_build_events for 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's unknown_capability switches to the
      documented compatibility contract: only M-1 (churn / GBDT classification) runs;
    • datasets: list_datasets;
    • Pipelines: list_projects, then get_project for each project; only graphs with
      approval: approved whose methodology (if any) is runnable are offered for grants, the others
      are listed as not runnable.
  2. 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.
  3. Checks the answer by rule (defects). An answer is a question, a decline (naming a
    methodology or a solution, with its tracking issue) or a proposal. A proposal is rejected when:
    • its type is not native or python, 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, project or dataset;
    • 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 live app-events.<app-id>, a live build-events.<build-id> or build-events.*,
      proposes an App or build change outside the grant, does not delegate changes to
      agent-application with turn kind app, or its agent.toml tools differ 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 exactly decide, 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.toml asks for other dependencies; something looks like a secret;
    • a Python agent is not stored in zetta or lake, or is stored in zetta with more than 900 KiB
      of code.
  4. 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.
  5. 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 with message (or request), conversation_id, lake_token,
      customer_id, and optionally workspace_id, page and lake_url. When AGENT_SERVICE_TOKEN
      is set, the request must carry Authorization: Bearer <that token>. The answer is
      {ok, conversation_id, trace_id, reply, result, calls, rounds, finished, proposals}: 200 when
      it answered, 422 when the turn failed, 400 for a body that is not JSON or has no message,
      401 without the token;
  • works per turn: each turn's lake_token and customer_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 named http, 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) and AGENT_BUS_AGENT=agent-creator.

  • Lake learns its address from LAKE_AGENT_ENDPOINTS (agent-creator=<url>, among the other
    library agents), and presents LAKE_AGENT_SERVICE_TOKEN as the bearer.

  • Turns arrive over the agent bus (lake docs/api/agent-bus.md, lake#269). Lake publishes each
    task id on agent-tasks.agent-creator on lake's Zetta (task ids only, never content). The
    runtime's bus client (agent_runtime.lake_bus, started only when AGENT_PER_TURN_CREDENTIALS=1
    and LAKE_URL, AGENT_BUS_TOKEN and AGENT_BUS_AGENT are all set):

    1. long-polls receive_agent_tasks (10-second wait) from sequence 1 at start;
    2. calls claim_agent_task for each task; a conflict or not_found means another replica won;
      the claim answers the turn body with the task's lat. credential in it;
    3. runs up to four turns at once; for each it publishes one progress event (Working on it),
      runs the same turn handler as /v1/turn, then publishes result (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.

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
    (defects plus case facts; no judge). Reports land in reports/; 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 prod on the managing cluster orama-production-cluster-01 (namespace lake; the
    development environment) pins oramasearch/agent-creator:6b1cc36-f8feb14 in its spec.agents.
  • LakeSet lake-nonprod (members dev, staging, testing on orama-nonprod-cluster-01) and
    LakeSet lake-prod (members shared on orama-production-cluster-02, shared-us on
    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's prior_turn field.

Known issues

Security-relevant first.

  1. Workspace identity is not passed explicitly on every call
    (agent-creator#9, with
    agent-runtime#6): App and build reads
    carry only customer_id, the bus client takes no workspace_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.
  2. list_methodologies is not one of its tools. Its record grants search and summarize, and
    only train and pipelines grant list_methodologies. Deployed, the read fails with
    'list_methodologies' is not one of this agent's tools, so the methodology registry is
    unavailable for 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.
  3. The structured answer is shipped, the issue is still open
    (agent-creator#1): reply is now words
    and result carries the structure; the issue stays open for lake's side to read result.
  4. Lake's documentation describes a narrower turn key than this agent uses: lake's
    docs/api/agent-launches.md says 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)