Umbrella Local Agent Runtime

Umbrella: Local Agent Runtime

Issue: noetl/ai-meta#474 · Opened: 2026-10-17 · Status: ✅ CLOSED 2026-10-17: shipped through noetl CLI 5.3.1 / noetl-tools 4.2.0 / PyPI 5.3.0.

Closing summary. NoETL now runs AI agents in --runtime local as playbooks, with no Python. framework: claude bills an API key, and NoETL runs each tool as a sub-playbook; framework: claude-code runs headless claude -p on a Claude subscription. There's a local credential store with google_oauth. The agent-playbooks showcase triages four real Gmail inboxes at ~2–3¢/run. Two defects surfaced by the work were fixed: a max_tokens cut-off returning empty "success" (tools 4.2.0), and render_template re-expanding substituted values (CLI 5.3.1). Distributed kind: agent remains out of scope.

Goal

Run AI agents with NoETL in --runtime local, written as playbooks, with no Python and no resident agent process. It's a local, scheduled alternative to always-on agents such as OpenClaw. The worked example is a daily triage across four real Gmail inboxes, read-only.

Background

• kind: agent existed only in the retired Python worker (removed 2026-08-30, noetl 25bef859).
• The Rust server rejects agent at registration (#256). #447 records that agent / mcp are valid in one kind namespace and rejected in the other.
• This umbrella is local runtime only. Distributed kind: agent would need a callback-shaped design so a model turn doesn't hold a worker slot.

Shape

• noetl-tools AgentSession: a turn-by-turn Messages API loop. The host runs the agent's tools between turns: the CLI runs each as a sub-playbook. The state is plain JSON message history.
• framework: claude bills an API key, and NoETL sees and gates every tool call.
• framework: claude-code runs the official CLI headless (claude -p) on a Claude subscription, with the API-key env stripped.
• Credentials: a local store (env var or mode-600 file), http auth bearer / api_key / google_oauth, and noetl credential google for installed-app OAuth with PKCE.

Recent activity

Date	Change	Where
2026-10-16	AgentSession + claude-code → noetl-tools 4.1.0	tools#112
2026-10-16	Tool::Agent in the local runtime → CLI 5.1.0, executor 0.11.0	cli#95
2026-10-16	PyPI wrapper 5.2.0 (CLI 5.1.0)	noetl#710
2026-10-17	Credential store, http auth aliases, noetl credential → CLI 5.2.0, executor 0.12.0	cli#96
2026-10-17	Prompt caching, thinking / effort, max_tokens no longer passes as success → noetl-tools 4.2.0	tools#113
2026-10-17	CLI pass-through → CLI 5.3.0, executor 0.13.0	cli#97
2026-10-17	PyPI wrapper 5.3.0 (CLI 5.3.0), verified via pip in a fresh venv	noetl#711
2026-10-17	Showcase repo + wiki (tutorial, architecture, Connect Gmail)	noetl/agent-playbooks
2026-10-17	Single-pass render_template + spool-test deflake → CLI 5.3.1, executor 0.13.1	cli#98, cli#99

What the measurements said

• Cost: four inboxes cost $0.35/run on Sonnet, and about 2–3¢ on Haiku with thinking: disabled, the Primary tab only, compacted tool output (rhai) and prompt caching. Tokens went from 87,715 in / 6,148 out to 8 in + 8,158 cache-write + 2,126 cache-read / 2,667 out.
• ⚠ Silent success: Haiku spent a summary turn's whole max_tokens on a thinking block, and the run was reported as successful with empty text. Fixed in 4.2.0: such a turn now fails and names the content block types.
• ⚠ Template re-expansion: render_template re-expanded substituted values in HashMap order. That's nondeterministic, and lets untrusted data read other variables. It was found by the agent end-to-end test and stopgapped with defang_template_markers; the real fix is cli#98.

Next concrete steps

• cli#98: single-pass template rendering, released in CLI 5.3.1 / executor 0.13.1.
• cli#99: spool test deflaked (released with 5.3.1).
• Owner: publish the Google OAuth app (project akuksin) or re-authorize weekly. In Testing, refresh tokens expire after 7 days.
• PyPI wrapper 5.3.1 (CLI 5.3.1, executor 0.13.1; noetl#712), verified with a re-expansion probe: 5.3.0 leaked 30/30, 5.3.1 0/30.
• #477: second render of local shell/http steps, fixed in CLI 5.3.2 (cli#100). defang_template_markers is now defence in depth only; it can be removed in a cleanup. Optional: a Secret Manager backend for the credential store.

Related pages

noetl/tools wiki: AgentTool · noetl/cli wiki: kind: agent · noetl/cli wiki: Credentials · agent-playbooks wiki