Skip to content

Release v0.1.0

Choose a tag to compare

@homer6 homer6 released this 17 Oct 22:51
· 46 commits to main since this release
f3ebbe4

agent-runtime v0.1.0

Released 2026-10-17. The first release. One Python package, agent-runtime, and one private
image, docker.io/oramasearch/agent-runtime:v0.1.0. It is the blank Python agent: the image every
user-created agent in Lake runs on. It holds no agent of its own. At start it reads the agent's record
from its workspace through Lake, loads the agent's instructions and code, derives the agent's tools
from Lake's OpenAPI and the skills a person granted, and runs the agent on the OpenAI SDK pointed at
Lake's model gateway. A new agent is data, not an image. Proprietary to Orama; private repository
and image.

It is not a library agent. The Agent Library's specialized agents (Ask Orama, the Project Agent,
Auto-Suggest and the rest) have their own repositories and images. One of them, AgentCreator, is
built on this image (FROM oramasearch/agent-runtime:${RUNTIME_TAG} in agent-creator's
Dockerfile), which is the only way this runtime takes work from Lake's agent bus.

What it includes

Two modes

The mode is --mode or AGENT_MODE (default job).

Mode What it does
job Reads AGENT_INPUT (JSON; null when empty), runs the agent once, prints the summary and the whole result to stdout as one JSON line, and writes a summary of at most 4,000 characters (trace_id, exit, reply, error, number of calls) to /dev/termination-log, which the operator reads back into the launch's status. Exit code 0: answered; 2: finished without an answer (or stopped at the round limit); 1: could not load or run
service An HTTP server on PORT (default 8080) that keeps each conversation's messages in memory, so a turn continues the one before it

The service HTTP API (runner.py):

Route What it does
GET /healthz {ok, agent, name, tools, model, version}: the agent's id and name, its tool names, its model, and this runtime's version (new in this release, read from the installed package). No authorization
POST /v1/turn Body {message (or request), conversation_id?, page?, customer_id?, and for a per-turn agent lake_token, lake_url?, workspace_id?}. When AGENT_SERVICE_TOKEN is set, Authorization: Bearer <it> is required (401 otherwise). Answers 200 with {ok, conversation_id, trace_id, reply, calls, rounds, finished, proposals, result?}, or 422 with {ok: false, error, ...} when the turn failed; 400 when the body is not JSON or has no message; 404 for any other route

conversation_id is generated when omitted. A turn's answer carries every tool call with its
observation or error (calls), every proposal it recorded (proposals), and, from an entrypoint that
returns one, a structured result beside the words.

Per-turn credentials (AgentCreator)

With AGENT_PER_TURN_CREDENTIALS=1 the service loads no agent from Lake at start: its definition is
built into the image (--definition-dir or AGENT_DEFINITION_DIR, a record.json beside its files,
loaded in place as source dir). Each turn must carry the asking person's lake_token and
customer_id; the turn's tools are derived from that person's workspace, and its model calls use that
token. In this mode only, the service also takes turns from Lake's agent bus (below).

How it loads an agent (definition.py, lake.py)

The record is Lake's get_agent {id}, as the launch's customer and workspace, or a file given with
--record. Only an agent with runtime: python is run. Its definition has one source:

Source Where the files are
zetta inline on the record: instructions and files [{path, contents}]
lake a Lake repository at a pinned revision, read with repository_tree and repository_file
dir a directory built into an image layered on this one (--definition-dir, AGENT_DEFINITION_DIR)

The layout is the same in every source: agent.toml (optional: entrypoint = "module:function",
model, tools as an allow-list, dependencies), instructions.md (optional when the record carries
instructions), and agent/ (optional code: agent/tools.py may export TOOLS, plain callables; an
entrypoint may run its own loop). A form-built agent has no files: its system prompt is composed from
the record's name, purpose, manifesto and goal.

Refused at load, before any model call, with exit 1 (job) or a cannot load line and exit 1
(service): a runtime other than python; a source other than zetta, lake or dir; a lake
source without repository_id or revision; a dependency outside ALLOWED_DEPENDENCIES (openai,
httpx, pydantic, pandas, numpy), which is never installed at run time; an entrypoint whose
module is not in the definition; a file path outside the definition; an agent.toml that does not
parse; and a Lake OpenAPI that cannot be read.

Its tools (tools.py), derived, never hand-written

Every tool's input schema comes from an OpenAPI document at run time. customer_id and
workspace_id are removed from every schema the model sees and filled from the launch (CUSTOMER_ID,
WORKSPACE_ID), so a model cannot point a call at another account or workspace. An agent.toml
tools allow-list narrows the final list; it cannot add anything.

  1. Lake's capabilities, from Lake's token-filtered OpenAPI (GET <LAKE_URL>/v1/openapi.json),
    called as /v1/<name>. An operation whose x-lake-action is read is a tool that calls Lake;
    any other is a proposal tool: it records {capability, input, impact} in the turn's
    proposals, answers PROPOSED, NOT DONE, and sends nothing to Lake. The exception is a skill's
    direct engine actions, which the runtime calls and the engine's own policy governs.
  2. App and build capabilities, for every agent (apps.py). Reads: list_apps, get_app,
    app_logs, receive_app_events, list_builds, get_build, build_logs, receive_build_events.
    Proposals only: create_app, deploy_app, rollback_app, delete_app, set_app_env,
    unset_app_env, set_app_auth, restart_app, stop_app, start_app, scale_app,
    set_app_zetta_binding, bind_service_to_app, unbind_service_from_app,
    create_service_and_bind_to_app, build_image, build_app, cancel_build. Each turn gets a
    system message naming these and the agent-application specialist. See
    App and build capabilities.
  3. Granted Pipelines: each {project, graph} on the record is a tool pipeline_<graph> that calls
    check_pipeline (a blocked gate runs nothing and names the failing checks), start_run, polls
    get_run every five seconds for up to ten minutes, and returns get_run_report (or the run id to
    poll, after ten minutes).
  4. MCP connections (mcp.py): each mcp:<prefix> skill grants the allowed tools of that
    workspace MCP connection, listed with list_mcp_connection_tools {allowed_only: true}, as
    <prefix>__<tool> with the server's own schema. A read calls read_mcp_tool; a change a person
    auto-approved for this agent calls call_mcp_tool; any other change is a call_mcp_tool
    proposal. Every answer is wrapped as data, never instructions. See MCP.
  5. The definition's own functions: agent/tools.py's TOOLS, described by their docstrings.

The work area on the record narrows every Lake read and direct action: a project-confined agent
cannot name another project, a dataset-confined one cannot name another dataset. A refused or failing
call is returned to the model as an observation, never raised.

Skills (skills.py, skills.json)

Twelve skills, plus mcp:<prefix>. skills.json (generated by tools/write-skills-json.py) lists
each skill's reads, proposals and direct capabilities; Lake vendors it, offers exactly these
skills in the Agent Factory and on the agent pages, and gives a launch's credential the reads of its
agent's skills and no change.

Skill Label Reads Proposals Direct
search Search data 18 3 none
generate-data Generate a dataset 2 0 generate_dataset
train Train a Model 32 4 check_pipeline, start_run
summarize Summarize and explain 21 0 none
call-api Call the API 15 3 (approve_decision among them) decide, record_outcome
drives Use drives 14 16 none
transcripts Use transcripts 2 4 none
repositories Work in repositories 24 16 none
datasets Load datasets 7 7 none
streams Read and publish streams 3 6 none
pipelines Design pipelines 16 43 none
usage Read usage and billing 8 0 none

The capability names per skill are in skills.json; why the five direct actions
are direct and approve_decision is a proposal is in Skills.
NEVER_FOR_AGENTS names 296 capabilities no skill may grant, each group with its reason (sign-in,
recovery, key and certificate minting, secrets, people and access, SSO and SCIM, audit and the
transparency log, billing changes, workspaces and infrastructure, webhooks, the generic
workspace_query / workspace_act / workspace_sql, other agents and the agent bus, MCP connection
management, events only an App, a build or the operator publishes, a methodology run's runner side).
The contract (tests/test_skills.py): every one of the 537 capabilities in the vendored Lake
OpenAPI (tests/fixtures/lake-capabilities.json) belongs to a skill, to the App and build set, or to
the never list, and skills.json is what skills.py and that fixture produce.

Solutions (solutions.py)

When an agent's grants include list_solutions and get_solution (skills search, train,
summarize, call-api), each turn reads list_solutions and get_solution for every returned id
and puts those records in the turn's context (Context.solution_catalog for an entrypoint). An
unknown_capability answer, or catalogue: {available: false}, is reported to the model as not
deployed yet. See Solution capabilities.

The prompt and the loop (loop.py)

The system prompt is the agent's instructions (or the composed form) followed by the runtime's
PREAMBLE: tools are the only source of facts, a failing tool is reported, a "Propose" tool changes
nothing, and the work area. The runtime has no prompt-version constant; the prompt that ships is
the PREAMBLE text in this tree. The default tool loop runs at most MAX_ROUNDS = 12 rounds. An
entrypoint is handed a Context (agent, input, tools, client, model, solution_catalog,
app_capabilities, call_tool, complete) and may answer a string, a Result, or
{"reply": <words>, "result": {...}}.

The model, through Lake (model.py)

Every model call goes to <LAKE_URL>/openai/v1 with the run's own Lake credential as the API key:
LAKE_TOKEN for a launch, the turn's lake_token for a per-turn agent. Lake calls the provider with
Orama's key and counts the tokens in the run's workspace. The runtime reads no provider key, and an
entrypoint's context.client is that same client. The model is agent.toml's model, else the
record's model_name, else AGENT_MODEL, else gpt-5.5.

Traces

Every job and every service turn, failures included, writes <TRACE_DIR>/<trace id>.json: the agent,
the mode, the time, the input and the whole result (calls, observations, proposals). No credential is
written.

Command line and environment

[project.scripts]: agent-runtime (agent_runtime:main), with --mode job|service,
--agent-id (overrides AGENT_ID), --record <file> (an agent record instead of get_agent) and
--definition-dir <dir>.

Variable Meaning
LAKE_URL Lake's address; for a launch the operator gives the workspace's path on Lake's in-cluster address
LAKE_TOKEN The run's Lake credential: a launch's lal.<launch id>.<secret>, a schedule's las.<schedule id>.<secret>
CUSTOMER_ID, WORKSPACE_ID The account and workspace every call is fixed to
AGENT_ID The agent record to load
AGENT_MODE job or service
AGENT_INPUT A job's task, as JSON
AGENT_MODEL The model when neither the definition nor the record names one
AGENT_SERVICE_TOKEN When set, the bearer POST /v1/turn requires
AGENT_PER_TURN_CREDENTIALS 1: credentials and workspace come with each turn, and the bus is used (AgentCreator)
AGENT_DEFINITION_DIR A definition built into the image (default of --definition-dir)
AGENT_BUS_TOKEN, AGENT_BUS_AGENT The library agent's own bus credential and its agent key (per-turn mode only)
TRACE_DIR Where traces go (image default /tmp/agent-runtime-traces)
PORT The service's port (default 8080)

Tools in the repository

  • tools/vendor-lake-capabilities.py <url or file> writes tests/fixtures/lake-capabilities.json
    from a Lake's OpenAPI (start Lake with LAKE_BILLING=on).
  • uv run tools/write-skills-json.py regenerates skills.json from skills.py and that fixture.

How Lake reaches it

A person's own agent: launches, run by the Orama operator. Lake writes a launch into its
agent_launches table (launch_agent, a schedule, or a stream trigger); the operator
(internal/controller/lake_agents.go) runs it from spec.agents.runtimeImage in the workspace's
namespace:

  • job: a Kubernetes Job (backoffLimit: 0, deadline spec.agents.jobDeadlineSeconds or one
    hour), AGENT_MODE=job, the launch's input as AGENT_INPUT. The exit code and the termination-log
    summary become the launch's result. A schedule is a CronJob with the same Job template.
  • service: one Deployment (one replica) and Service on port 8080, with startup, readiness
    and liveness probes on GET /healthz, AGENT_MODE=service, and Lake's agent service token as
    AGENT_SERVICE_TOKEN. Lake's agent_turn to the agent sends POST /v1/turn (the message and the
    conversation id) to the launch's endpoint with LAKE_AGENT_SERVICE_TOKEN as the bearer.

Each launch gets a credential the operator generates, lal.<launch id>.<secret>, in a Secret the pod
reads as LAKE_TOKEN; only its SHA-256 is written to Lake. It acts as the person who launched it,
limited to the launch scopes of the agent's skills. Every pod runs as user 10001, non-root, with a
read-only root filesystem, a writable /tmp, all capabilities dropped and no Kubernetes token.

A person's own agent never uses the agent bus. The operator gives it no bus credential, and the
runtime starts the bus client only when AGENT_PER_TURN_CREDENTIALS=1.

AgentCreator, through the agent bus. The library agent agent-creator (an image layered on this
one, per-turn credentials) runs as a library agent: one Deployment and Service on port 8080, with
/healthz, its address given to Lake in LAKE_AGENT_ENDPOINTS. Its turns arrive as tasks on Lake's
agent bus (Lake docs docs/api/agent-bus.md), the topic agent-tasks.agent-creator on Lake's own
Zetta, which carries task ids, never content. lake_bus.py does exactly this, with the agent's own
bus credential (AGENT_BUS_TOKEN) and through Lake, never holding the bus's token:

  1. receive_agent_tasks {agent, from_sequence, wait_ms: 10000} (GET) long-polls, starting at
    sequence 1 and continuing from next_sequence; a failed receive waits two seconds and retries.
  2. claim_agent_task {task_id, agent} (POST) takes each task; a conflict or not_found means
    another replica took it and is skipped. The claim answers the task's body with its lat. task
    credential, which becomes the turn's lake_token.
  3. The turn runs in a pool of four workers, exactly as POST /v1/turn would.
  4. publish_agent_event (POST) reports progress ("Working on it"), then result with the whole
    answer, or failed with the error.

It does not send workspace_id on these calls (Lake takes it from the task row), does not renew the
claim's lease, and does not back off after an empty receive (agent-runtime#6, below).

The image

docker.io/oramasearch/agent-runtime, private on Docker Hub. Dockerfile: a build stage on
python:3.12-slim with uv 0.11.7 copied from ghcr.io/astral-sh/uv:0.11.7 runs
uv sync --frozen --no-dev --no-editable; the final stage is python:3.12-slim with that virtual
environment, user agent with uid 10001 (USER 10001), TRACE_DIR=/tmp/agent-runtime-traces,
PORT=8080, EXPOSE 8080, and ENTRYPOINT ["agent-runtime"]. It needs only the repository as its
build context: no named build contexts. Built on the cluster BuildKit for linux/amd64, never with
Docker on a workstation.

  • Digest: docker.io/oramasearch/agent-runtime:f3ebbe4@sha256:f14cbc7b7f82d3a9bb54635011d9b5daf019cd89c41e38dce7b00185e297e73f, also tagged :v0.1.0 (same digest).

Where it runs

Every Lake runs it: it is the image of every user-created agent's launch, schedule and stream run.

  • The operator's default (orama-operator internal/controller/lake_defaults.go on dev):
    lakeDefaultAgentRuntimeImage = "oramasearch/agent-runtime:f8feb14". AgentCreator's default image
    is oramasearch/agent-creator:6b1cc36-f8feb14, built on the same runtime commit.
  • Lake prod on the managing cluster orama-production-cluster-01 (namespace lake; the
    development environment, despite the name) pins spec.agents.runtimeImage: oramasearch/agent-runtime:f8feb14.
  • The LakeSets lake-nonprod (members dev, staging and testing on
    orama-nonprod-cluster-01) and lake-prod (members shared on orama-production-cluster-02 and
    shared-us on orama-production-cluster-03) take the operator's default.

v0.1.0 is the same tree as that running commit, f8feb14, plus these release notes, the version
field on GET /healthz, and the test that holds the version (tests/test_release.py). Moving the
operator's default to oramasearch/agent-runtime:v0.1.0 is a separate change in orama-operator.

What it does not include

  • No sandbox inside the pod. A definition's code (agent/tools.py, an entrypoint) runs in the
    runtime's own Python process, with the run's LAKE_TOKEN and, in a service, AGENT_SERVICE_TOKEN
    in its environment. The pod's own restrictions (non-root, read-only root filesystem, no Kubernetes
    token) are the only boundary today.
  • No dependency beyond the image's pinned set (openai, httpx, pydantic, pandas, numpy).
    Adding one is a runtime release.
  • No durable conversations. A service keeps conversations in memory; a restart forgets them, and
    a service launch is one replica.
  • No direct changes outside the five direct engine actions (check_pipeline, start_run,
    generate_dataset, decide, record_outcome) and auto-approved MCP tools. Every other change is a
    proposal a person confirms in Lake. record_action is not available: Lake does not publish it
    (lake#708).
  • No size check on an inline (zetta) definition in the runtime; any limit is the record's.
  • No eval scores. The runtime runs other people's agents; its evals are the Agent Factory's and
    Lake's live agent end-to-end proofs.
  • A Pipeline tool waits at most ten minutes, then returns the run id to poll.
  • The tool loop stops after twelve rounds with a reply saying so.

Known issues

Security-relevant first.

  1. Customer code can read the service token every library agent accepts. A user-created service
    launch is given Lake's shared agent service token as AGENT_SERVICE_TOKEN, and a definition's own
    code runs in the same process (above); Lake's agent-bus doc records that this is why that token is
    never a bus credential. Filed as agent-runtime#14; network sandboxing of agents and secure
    runtimes are oramasearch/lake#725.
  2. An agent's pods are not network sandboxed: definition code can open any connection the pod's
    network allows (oramasearch/lake#725).
  3. The bus client is not yet the workspace-aware cutover client: it sends no workspace_id, does
    not renew a claim's lease, and long-polls again at once after an empty receive instead of backing
    off to at most one receive a minute (#6).
  4. A service launch whose agent was deleted crash-loops: the runtime exits 1 at start
    (cannot read agent ...: not_found) and the Deployment restarts it until the launch is stopped
    (oramasearch/lake#524).
  5. The solution ledger has no action step through Lake: record_outcome needs an existing action,
    and record_action is not a Lake capability (oramasearch/lake#708).

Verification

Proof Result
Test suite (uv run --frozen pytest -q -ra, macOS arm64, Python 3.12) 67 passed, 0 failed, 0 skipped: tests/test_runtime.py, tests/test_skills.py, tests/test_mcp.py, tests/test_lake_bus.py, tests/test_release.py
Skills contract (tests/test_skills.py, in the suite) Every one of the 537 capabilities in the vendored Lake OpenAPI is accounted for; skills.json matches skills.py
Version pyproject.toml 0.1.0; importlib.metadata.version("agent-runtime") and GET /healthz report it (tests/test_release.py)
Live agent runs (a model through Lake's gateway) Not run for this release (needs a live model)
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-runtime:f3ebbe4
Image digest docker.io/oramasearch/agent-runtime:f3ebbe4@sha256:f14cbc7b7f82d3a9bb54635011d9b5daf019cd89c41e38dce7b00185e297e73f, also tagged :v0.1.0 (same digest); the Docker Hub repository answers 404 anonymously (private)