Repository navigation
Releases
Release v0.3.1
Released 2026-11-16. A patch release. One clean header in the Dockerfile, since v0.3.0. Nothing the runtime does has changed. Image: docker.io/oramasearch/agent-runtime:v0.3.1.
This release is the tree of dev after #45 (ccadaaf), with these notes and the version.
What changed
Every pull request merged into dev since v0.3.0 (git log --first-parent v0.3.0..origin/dev):
| PR | What it does |
|---|---|
| #44 | Records the v0.3.0 image digest in the v0.3.0 notes; documentation only |
| #45 | Gives the Dockerfile one clean header: the duplicated description is removed, and the comments no longer reference internal issues |
No source file under src/ changed, and no setting is new or removed (git diff v0.3.0..v0.3.1 -- src is empty).
Not included
- Claiming tasks by reference and naming the task on every call (#36): deferred for review, not in this release.
- Unchanged from v0.3.0 otherwise.
Known issues
Security-relevant first. Unchanged from v0.3.0.
- Service turns write every tenant's trace to the shared pod's disk (#38): a service turn's trace (the message, the answer and every tool observation) is written under
TRACE_DIRand never removed. - The image bundles GPL and LGPL code (#40): it is built on
python:3.12-slim(Debian: glibc, bash, coreutils, dpkg, readline). The move toscratchwith static binaries is deferred; it is noted here and does not block this release. - Dataset-confined launch credentials are not yet confined at Lake: the runtime refuses what it cannot prove, but the launch token itself still carries the person's reach.
- The bus client is not yet the workspace-aware cutover client (#6): no
workspace_idon every call, no lease renewal, no idle backoff. - One test fails (#41):
tests/test_lake_bus.py::test_a_task_is_claimed_run_and_answered_on_the_busstill expects a bus turn's body without theclaimthat v0.3.0 added. The behaviour is the intended one; the test was not updated with it.
Where it has run
The v0.3.1 tree had not run on a development environment when it was released. It differs from v0.3.0 only in Dockerfile comments. Lakes take the operator's default runtime image; moving it to :v0.3.1 is a separate operator change.
The image
Built from the tag v0.3.1 (4bc4b5b) with BuildKit (linux/amd64, the repository's Dockerfile), then tagged :v0.3.1 on that digest without rebuilding:
docker.io/oramasearch/agent-runtime:4bc4b5b@sha256:166a83183de2e7eaa368c67f8eb1def327641815a6690f9c824c4e850882f654, also tagged :v0.3.1 (same digest). The image is published on Docker Hub; its GPL/LGPL base is a known issue (#40).
Pinning it on a Lake is a separate change to the operator's defaults or the Lake's resource.
Verification
| Proof | Result |
|---|---|
Test suite (uv run --frozen --group dev pytest -q -ra, macOS arm64, Python 3.12) |
149 tests: 148 passed, 1 failed (#41, fails alone too), 0 skipped. tests/test_dataset_work_area.py 45, tests/test_skills.py 31, tests/test_runtime.py 25, tests/test_service_auth.py 13, tests/test_conversations.py 9, tests/test_turn_destinations.py 9, tests/test_bus_backpressure.py 6, tests/test_lake_bus.py 4 (1 failed), tests/test_mcp.py 4, tests/test_release.py 3 |
Skills contract (tests/test_skills.py, in the suite) |
Passed: every capability in the vendored Lake OpenAPI is accounted for; skills.json matches skills.py |
| Version | pyproject.toml and uv.lock 0.3.1; importlib.metadata.version("agent-runtime") and GET /healthz report it (tests/test_release.py) |
SPDX headers (python3 tools/spdx-headers.py --check) |
Passed |
SBOM (python3 tools/sbom.py --check) |
Passed, regenerated for v0.3.1 |
| Live agent runs (a model through Lake's gateway) | Not run for this release (needs a live model) |
| Dev environment | Not run (above) |
| Linux image build (BuildKit, from the tag) | Built from v0.3.1: oramasearch/agent-runtime:4bc4b5b, also :v0.3.1, sha256:166a83183de2e7eaa368c67f8eb1def327641815a6690f9c824c4e850882f654 |
Release v0.3.0
Released 2026-11-16. A minor release. The runtime's licence and open-source preparation, the bus consumer and conversation memory bounded, and the image's bases pinned by digest, since v0.2.0. The bounded bus and memory change behaviour a caller can see and add settings, which is why this is a minor release and not a patch. Image: docker.io/oramasearch/agent-runtime:v0.3.0.
This release is the tree of dev after #39 (f7e38b7), with these notes and the version.
What changed
Every pull request merged into dev since v0.2.0 (git log --first-parent v0.2.0..origin/dev):
| PR | What it does |
|---|---|
| #30 | Merges main back into dev after the v0.2.0 release; nothing new |
| #31 | Records the v0.2.0 image digest in the v0.2.0 notes; documentation only |
| #34 | Adds a security policy, SECURITY.md: how to report a vulnerability privately, and what we commit to |
| #35 | Pins the Dockerfile's base images (python:3.12-slim, ghcr.io/astral-sh/uv:0.11.7) by digest as well as by tag |
| #33 | Bounds the bus consumer and the conversation memory, and keys a bus turn's history by the account, workspace and task chain Lake names |
| #37 | Prepares the tree for a public export: internal links, names and wording removed from the README, the docs and the release notes |
| #39 | The MIT licence: LICENSE, COPYRIGHT, an SPDX header in every source file, THIRD_PARTY_LICENSES, CONTRIBUTING.md, CLA.md, CODE_OF_CONDUCT.md, and the SBOM (sbom.spdx.json, sbom.cdx.json, tools/sbom.py) |
The licence — #39
agent-runtime is released under the MIT licence, copyright OramaSearch, Inc. (LICENSE, COPYRIGHT). Every source file carries SPDX-License-Identifier: MIT, added and checked by tools/spdx-headers.py. THIRD_PARTY_LICENSES lists the licence of every dependency. Contributions are made under CLA.md (contributors assign copyright to OramaSearch, Inc.), following CONTRIBUTING.md and CODE_OF_CONDUCT.md. tools/sbom.py writes the software bill of materials in SPDX 2.3 and CycloneDX, regenerated for this release.
A security policy — #34
SECURITY.md says how to report a vulnerability privately and what we commit to in reply.
The bus consumer and the conversation memory are bounded — #33
- The bus consumer claims a task only when a worker is free to run it. Nothing is received while every worker is busy, so claimed tasks (and their credentials) no longer pile up in memory, and a task left unclaimed stays on the bus for another replica.
AGENT_BUS_WORKERS(default 4) run at once; one customer holds at mostAGENT_BUS_TENANT_WORKERS(default one fewer), so one tenant's burst cannot take every worker. At most 256 dispatch rows wait. - Every bus turn carries Lake's claim (
task_id,customer_id,workspace_id) asclaim. - Conversation memory is bounded. At most
AGENT_CONVERSATIONSconversations (default 256), each at mostAGENT_CONVERSATION_TURNSturns (20) andAGENT_CONVERSATION_BYTES(1 MiB), all of them at mostAGENT_CONVERSATIONS_BYTES(64 MiB); one idle forAGENT_CONVERSATION_IDLE_SECONDS(3600) is dropped. - A bus turn continues only the conversation its
prior_turnleft in the same account and workspace, never one named by a caller'sconversation_id. A directPOST /v1/turnkeeps its ownconversation_idkey in a separate namespace, so it cannot reach a bus turn's history. A turn that raises is rolled back.
The image's bases are pinned by digest — #35
Each FROM and COPY --from names the multi-platform index digest its tag pointed to, so a later build of the same source gets the same base. A new base is a reviewed change of the digest.
Prepared for a public export — #37
Links to issues and pull requests, internal names and wording are removed from the README, the docs and the earlier release notes. The agent files (CLAUDE.md) ship with the repository.
Behaviour changes to know before it rolls
- A bus turn's history is keyed by Lake's claim, not by the
conversation_idin its body. A bus caller that relied on naming a conversation to continue it continues only the chain itsprior_turnnames. - Conversations are forgotten past the limits above, oldest or idle first.
- The bus consumer runs at most
AGENT_BUS_WORKERSturns at once and leaves the rest on the bus.
Settings it needs
No setting is required. Seven optional settings are new, each with the default above: AGENT_BUS_WORKERS, AGENT_BUS_TENANT_WORKERS, AGENT_CONVERSATIONS, AGENT_CONVERSATION_TURNS, AGENT_CONVERSATION_BYTES, AGENT_CONVERSATIONS_BYTES and AGENT_CONVERSATION_IDLE_SECONDS. git diff v0.2.0..v0.3.0 -- src adds no other environment read.
Not included
- Claiming tasks by reference and naming the task on every call (#36, for lake#871): deferred for review, not in this release.
- Unchanged from v0.1.0 otherwise.
Known issues
Security-relevant first.
- Service turns write every tenant's trace to the shared pod's disk (#38): a service turn's trace (the message, the answer and every tool observation) is written under
TRACE_DIRand never removed. - The image bundles GPL and LGPL code (#40): it is built on
python:3.12-slim(Debian: glibc, bash, coreutils, dpkg, readline), so the image is not published. It moves toscratchwith static binaries before it is. - Dataset-confined launch credentials are not yet confined at Lake (lake#1055): the runtime refuses what it cannot prove, but the launch token itself still carries the person's reach.
- The bus client is not yet the workspace-aware cutover client (#6): no
workspace_idon every call, no lease renewal, no idle backoff. - One test fails (#41):
tests/test_lake_bus.py::test_a_task_is_claimed_run_and_answered_on_the_busstill expects a bus turn's body without theclaimthat #33 adds. The behaviour is the intended one; the test was not updated with it.
Where it has run
The v0.3.0 tree had not run on a development environment when it was released. Lakes take the operator's default runtime image; moving it to :v0.3.0 is a separate operator change.
The image
Built from the tag v0.3.0 (555e403) with BuildKit (linux/amd64, the repository's Dockerfile), then tagged :v0.3.0 on that digest without rebuilding:
docker.io/oramasearch/agent-runtime:555e403@sha256:6917619aeb7cc03a93df29c0bbff38ef6e93d5314c3cd162a0123e7bb1390b52, also tagged :v0.3.0 (same digest). The image is not published (#40).
Pinning it on a Lake is a separate change to the operator's defaults or the Lake's resource.
Verification
| Proof | Result |
|---|---|
Test suite (uv run --frozen --group dev pytest -q -ra, macOS arm64, Python 3.12) |
149 tests: 148 passed, 1 failed (#41, fails alone too), 0 skipped. tests/test_dataset_work_area.py 45, tests/test_skills.py 31, tests/test_runtime.py 25, tests/test_service_auth.py 13, tests/test_conversations.py 9 (new), tests/test_turn_destinations.py 9, tests/test_bus_backpressure.py 6 (new), tests/test_lake_bus.py 4 (1 failed), tests/test_mcp.py 4, tests/test_release.py 3 |
Skills contract (tests/test_skills.py, in the suite) |
Passed: every capability in the vendored Lake OpenAPI is accounted for; skills.json matches skills.py |
| Version | pyproject.toml and uv.lock 0.3.0; importlib.metadata.version("agent-runtime") and GET /healthz report it (tests/test_release.py) |
SPDX headers (python3 tools/spdx-headers.py --check) |
Passed |
SBOM (python3 tools/sbom.py --check) |
Passed, regenerated for v0.3.0 |
| Live agent runs (a model through Lake's gateway) | Not run for this release (needs a live model) |
| Dev environment | Not run (above) |
| Linux image build (BuildKit, from the tag) | Built from v0.3.0: oramasearch/agent-runtime:555e403, also :v0.3.0, sha256:6917619aeb7cc03a93df29c0bbff38ef6e93d5314c3cd162a0123e7bb1390b52 |
Release v0.2.0
agent-runtime v0.2.0
Released 2026-10-25. A minor release. Three security fixes from the 2026-10-21 Lake pre-launch
security review (orama-bridge#223) since
v0.1.0. They change behaviour a caller can see, which is why this is a minor release and
not a patch. Private repository and image, docker.io/oramasearch/agent-runtime:v0.2.0. Tracking
issue: #27.
This release is the tree of dev after #26
(fdb6714), with these notes and the version.
What changed
Every pull request merged into dev since v0.1.0
(git log --first-parent v0.1.0..origin/dev):
| PR | What it does |
|---|---|
| #16 | The v0.1.0 release pull request (dev promoted to main); nothing new |
| #17 | Records the v0.1.0 image digest in the v0.1.0 notes; documentation only |
| #19 | POST /v1/turn compares the service token in constant time, and refuses every turn when AGENT_SERVICE_TOKEN is unset (#18) |
| #21 | A turn's credential is sent only to Lake at this service's LAKE_URL, never to a lake_url the turn names (#20) |
| #26 | A dataset-confined agent's tools are checked against complete dataset identities, and reads that cannot be proven inside the dataset are refused (LSR-181, #23) |
The service token is compared in constant time, and required — #19
POST /v1/turn checks the bearer with hmac.compare_digest instead of !=, so the comparison no
longer leaks timing. The route now fails closed: with AGENT_SERVICE_TOKEN unset or empty, every
turn is refused with 503. In v0.1.0 an unset token left the route open. A wrong or missing bearer is
401, as before. Turns from Lake's agent bus are not affected.
A turn's credential goes only to LAKE_URL — #21
A per-turn agent (AgentCreator) made its model client from the turn's lake_url, so a caller of
POST /v1/turn, or a crafted bus task, could have the turn's lake_token sent to a host it named.
The turn's lake_url is no longer read. The model client and the per-turn Lake client both use this
service's LAKE_URL. When LAKE_URL is unset, empty, not an absolute http(s) address, or carries
user info, the turn is refused before any request goes out.
Dataset-confined agents: complete identities, provable reads only — #26
An agent whose work area is a dataset compared only table basenames, and did not check search
targets, so its model calls could reach other datasets the launching person can read. Now:
- dataset selectors are compared as complete
database/tableidentities, and the authorized
canonical identity is what is sent to Lake. Slash and dot forms both work; a bare name means Lake's
defaultdatasetsdatabase; - only
get_datasetand a filteredlist_datasetsare allowed, their answers are checked against the
work area, unscoped list metadata is dropped, and server errors are sanitized; - every other read and direct action is refused, including both search routes and the App and build
reads. Pipeline, MCP and definition model tools are left out of dataset-confined runs. Exact
proposals are still available, since they make no outbound call; - an empty or malformed work area, and a missing, malformed or conflicting selector, are refused.
Workspace and project work areas behave as before.
Behaviour changes to know before it rolls
- Dataset-confined agents lose some reads (#26). Index search, the App and build reads, and any
other read that cannot be proven inside the dataset are refused. Index search stays refused until
Lake can establish an index's source database (Zetta resolves a bare source table across databases
by first match); the Lake side is lake#1055.
A grant naming a bare table no longer authorizes the same basename in every database, and legacy
identities with punctuation outside SQL identifiers fail closed. - A service with no
AGENT_SERVICE_TOKENrefuses every turn with503(#19). Hand-run services
that relied on the open route must set the token. - A per-turn service with no valid
LAKE_URLrefuses every turn (#21), and the turn'slake_url
field is ignored.
Settings it needs
No new setting. AGENT_SERVICE_TOKEN and LAKE_URL are now required for service mode to take
turns; the operator already renders both (and AGENT_MODEL) on every agent launch, so a launch made
by the operator needs nothing new. git diff v0.1.0..v0.2.0 -- src adds no other environment read.
Not included
Unchanged from v0.1.0. The review's open follow-ups for this
repository are not in this release (below).
Known issues
Security-relevant first.
- Customer code can read the service token every library agent accepts: a user-created service
launch is given Lake's shared agent service token, and definition code runs in the same process
(#14,
orama-operator#793 LSR-044,
lake#1039). - An agent's pods are not network sandboxed
(lake#725). - The bus consumer claims tasks into an unbounded executor queue before a worker is free, so one
tenant's burst delays the others and its claims' leases run while queued (LSR-075, medium,
#24). - Service mode keeps unbounded conversation histories, shared by every tenant on the Lake, keyed
only by the body'sconversation_id(LSR-076, medium,
#25). - Dataset-confined launch credentials are not yet confined at Lake: the runtime refuses what it
cannot prove, but the launch token itself still carries the person's reach
(lake#1055). - The bus client is not yet the workspace-aware cutover client: no
workspace_id, no lease
renewal, no idle backoff (#6). - The solution ledger has no action step through Lake
(lake#708).
The review's findings for this repository are tracked in
#22.
Where it has run
The v0.2.0 tree has not run on the dev environment. No dev-<sha> build of agent-runtime was
pinned on the dev member of the lake-nonprod set; every member still takes the operator's default
oramasearch/agent-runtime:v0.1.0. Moving the runtime image to :v0.2.0 is a separate operator
change, rolled through testing, staging and prod, each behind its gate.
The image
Built from the tag v0.2.0 (4fd59b5) on the cluster BuildKit with build-agent.sh (linux/amd64, the repository's Dockerfile), then tagged :v0.2.0 on that digest without rebuilding:
docker.io/oramasearch/agent-runtime:4fd59b5@sha256:4c1d49174b924a66ddd3e0d07533957299dcca04fde3fa0d050a56fa6accced6, also tagged :v0.2.0 (same digest). The Docker Hub repository answers 404 anonymously (private).
It is not rolled anywhere yet: pinning it on an environment is a separate change to the operator's set files, through dev, testing, staging and prod in order.
Verification
| Proof | Result |
|---|---|
Test suite (uv run --frozen pytest -q -ra, macOS arm64, Python 3.12) |
134 passed, 0 failed, 0 skipped: tests/test_dataset_work_area.py 45 (new, #26), tests/test_runtime.py 25, tests/test_skills.py 31, tests/test_service_auth.py 13 (new, #19), tests/test_turn_destinations.py 9 (new, #21), tests/test_lake_bus.py 4, tests/test_mcp.py 4, tests/test_release.py 3 |
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 and uv.lock 0.2.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) |
| Dev environment | Not run (above) |
| Linux image build (cluster BuildKit, from the tag) | Built from v0.2.0 with build-agent.sh: oramasearch/agent-runtime:4fd59b5, also :v0.2.0, sha256:4c1d49174b924a66ddd3e0d07533957299dcca04fde3fa0d050a56fa6accced6; private (404 anonymously) |
Release v0.1.0
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.
- Lake's capabilities, from Lake's token-filtered OpenAPI (
GET <LAKE_URL>/v1/openapi.json),
called as/v1/<name>. An operation whosex-lake-actionisreadis a tool that calls Lake;
any other is a proposal tool: it records{capability, input, impact}in the turn's
proposals, answersPROPOSED, 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. - 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 theagent-applicationspecialist. See
App and build capabilities. - Granted Pipelines: each
{project, graph}on the record is a toolpipeline_<graph>that calls
check_pipeline(a blocked gate runs nothing and names the failing checks),start_run, polls
get_runevery five seconds for up to ten minutes, and returnsget_run_report(or the run id to
poll, after ten minutes). - MCP connections (
mcp.py): eachmcp:<prefix>skill grants the allowed tools of that
workspace MCP connection, listed withlist_mcp_connection_tools {allowed_only: true}, as
<prefix>__<tool>with the server's own schema. A read callsread_mcp_tool; a change a person
auto-approved for this agent callscall_mcp_tool; any other change is acall_mcp_tool
proposal. Every answer is wrapped as data, never instructions. See MCP. - The definition's own functions:
agent/tools.py'sTOOLS, 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.