The ApplicationAgent: builds web apps and data apps from a description, commits them to a lake repository, and deploys them as lake Apps after the person confirms. Built on agent-runtime.
Its image is published as oramasearch/agent-application on Docker Hub.
The Dockerfile pins its bases by multi-platform index digest (lake#1003): python:3.12-slim@sha256:5e2bdb1b… for both stages and ghcr.io/astral-sh/uv:0.11.7@sha256:240fb85a…. Moving one is a reviewed change of its digest.
Current release: v0.3.1 (all releases).
The Python service exposes POST /v1/turn and GET /healthz (which reports the version) on port
8080. POST /v1/turn requires Authorization: Bearer <AGENT_SERVICE_TOKEN>, compared in constant time (401 otherwise), and fails closed: with AGENT_SERVICE_TOKEN unset or empty it refuses every turn with 503. The operator always sets it; set it yourself for a hand-run service. Turns from lake's bus do not use it. It can also receive agent_turn tasks (lake gives them kind app) from lake's agent bus when
LAKE_URL and AGENT_BUS_TOKEN are set; AGENT_BUS_AGENT names the agent and defaults to
agent-application. Every app deployment remains subject to an explicit confirmation carried on a
follow-up turn. A confirmed proposal that needs packages outside app-runtime's baked set is first
stored as a source-backed runtime App, built by lake, and deployed from the resulting immutable
image reference.
A task is claimed only when a worker is free to run it at once (agent-application#33, LSR-075): while every
worker is busy nothing is received, and a task this replica cannot run stays unclaimed on the bus.
AGENT_BUS_WORKERS (default 4) run at once; one customer holds at most AGENT_BUS_TENANT_WORKERS
(default one fewer), and a freed worker goes to the waiting customer holding the fewest. At most 256
dispatch rows wait, never a claimed body. tests/test_bus_backpressure.py covers it.
The service's conversation memory is bounded (agent-application#34, LSR-076; conversations.py, ported
from agent-ask-orama): at most AGENT_CONVERSATIONS conversations (default 256), each at most
AGENT_CONVERSATION_TURNS turns (20) and AGENT_CONVERSATION_BYTES (1 MiB), all at most
AGENT_CONVERSATIONS_BYTES (64 MiB), dropped after AGENT_CONVERSATION_IDLE_SECONDS (3600) idle. A turn
that fails leaves nothing behind. A bus turn's conversation belongs to the account and workspace Lake's
claim reply names, never to ids in the body (LSR-008); a direct /v1/turn turn is kept apart from them.
The model is reached through lake (lake#248, lake docs/api/model-gateway.md): every call goes
to <LAKE_URL>/openai/v1 with the turn's own lake_token as the API key (model.py), so lake
counts its tokens in the turn's workspace and enforces the account's model-token limit. The service
holds no OPENAI_API_KEY; only the offline evals, which run for no workspace, call OpenAI directly. The model name is APPLICATION_AGENT_MODEL, else the Lake's AGENT_MODEL (set
by the operator from spec.agents.model), else gpt-6.1-sol (docs/operations/service.md).
A turn's credential goes only to Lake at this service's own LAKE_URL. Lake capabilities
and the model gateway are always reached at LAKE_URL; a turn's lake_url is ignored, so the
bearer is never sent to a host the caller names. With LAKE_URL unset, or not an absolute
http(s) URL without user info, query or fragment, every turn is refused before a request is made.
Development uses Python 3.12 and uv:
uv sync
uv run pytestSee the documentation index for the service contract, application workflow and releases.
An initial turn reads the person's lake metadata as needed, validates generated app.toml and
source, and returns result.kind: proposal with confirm: true. It performs no repository or App
writes. A follow-up turn must carry the reviewed object in context.confirmed_proposal; only then
does the agent commit the files, create or update the App, deploy it, and follow its rollout.
The follow waits up to three minutes for Ready: a starting pod's Degraded or failed probe is not
judged, only a state that is still there at the deadline (re-read with get_app). When the App
logs are unavailable the reply says so and never gives that as the reason it failed.
Retries reuse a repository or App with the proposal's exact name in the same customer, so a
failure after either row is created can resume from the reviewed proposal.
Every customer-owned read (repositories, datasets, services, App state, and image-build state)
carries the turn's customer_id. Build progress is read with receive_build_events and
get_build; build failures include the tail from build_logs.
Apps default to lake authentication and private source repositories. Zetta and Service credentials
are delivered through bindings. A secret environment value is a lake secret reference
(lake-secret://<mount id>/<name>#<field>), proposed only when the person names an existing secret;
otherwise the agent leaves it out and the person sets it on the App's Environment settings
(docs/building/apps.md). Dependencies outside app-runtime's baked set remain an image-mode
signal in the reviewed proposal. On confirmation, the agent creates a runtime App with the source
revision and a derived, non-secret APP_DEPS, asks lake to build it, waits for a terminal build
phase, and deploys the built image. Baked-only Apps skip the image build.
Lake also starts repair turns (an App failed) and change turns (more instructions for an App)
on an existing App named by context.app_id. The agent reads the App's events,
runtime logs, newest build, source and bindings, and proposes the change as a diff of the files it
changes. Confirmed, it commits them to the App's repository in one commit (each write a drip),
rebuilds when new packages need an image, redeploys and follows the rollout. An auto-fix turn,
which lake grants only when the person opted in and attempts remain, applies its own fix. See
docs/building/repair.md.
uv run pytest covers the service, bus, proposal rules, confirmation gate, deployment calls, and
generated Apps loaded by the pinned app-runtime revision, and whether a generated Streamlit App's sidebar
filters reach every metric, chart and table: the App runs under Streamlit's
AppTest over a SQLite copy of its dataset and each filter is chosen in turn
(agent_application.app_filters). Every proposal is also refused when a widget's value is assigned and
never used. The generation and change prompts require every filter to apply to the whole page, OR
instead of IN (the workspace's SQL has none), filter values as arguments of cached reads, and small
pages (tables of at most 1,000 rows, charts of aggregates). uv run application-agent-evals runs the
dashboard, Postgres CRUD, static-site and filtered-dashboard live model cases against deterministic
fake lake facts.
MIT, see LICENSE. Third-party components and their licenses are in THIRD_PARTY_LICENSES. Contributions are welcome under the Contributor License Agreement; see CONTRIBUTING.md.