keystone-cli 0.1.0__py3-none-any.whl

keystone_cli/runner.py

@@ -0,0 +1,87 @@
+"""Local graph run for ``keystone agent run`` (FDP-3120): per-node trace + ``--offline`` mock.
+
+The runner sets a LOCAL caller-identity ContextVar (so the SDK clients build headers) and, in
+offline mode, patches the SDK building-block clients so a run needs no live services / quota.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import contextmanager, nullcontext
+from typing import TYPE_CHECKING, Any
+
+import typer
+from keystone.agent_sdk import load_graph
+from keystone.request_context import LLMCallerIdentity, reset_caller_identity, set_caller_identity
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+# Minimal canned responses so an agent graph RUNS end-to-end offline (proves wiring, not real
+# answers). Keyed by the client operation (X-Caller-Operation). Record-replay cassettes = later.
+_OFFLINE_STUBS: dict[str, dict[str, Any]] = {
+    "chat_completion": {"choices": [{"message": {"content": "[offline stub answer]"}, "finish_reason": "stop"}]},
+    "embedding": {"data": [{"embedding": [0.0, 0.0, 0.0]}]},
+    "search": {"results": [{"chunk_id": "offline-1", "content": "[offline stub context]"}], "total": 1, "query_ms": 0},
+}
+
+
+def run_agent(*, entrypoint: str, project_dir: Path, inputs: dict[str, Any], offline: bool) -> dict[str, Any]:
+    """Load + run the agent graph locally with a per-node trace. Returns the final state."""
+    offline_ctx: Any = _offline_clients() if offline else nullcontext()
+    with _local_identity(), offline_ctx:
+        graph = load_graph(entrypoint, project_dir=project_dir)
+        return asyncio.run(_astream_with_trace(graph, inputs))
+
+
+async def _astream_with_trace(graph: Any, inputs: dict[str, Any]) -> dict[str, Any]:
+    final: dict[str, Any] = {}
+    # Two stream modes at once: "updates" names each node (trace); "values" carries the full
+    # state so the LAST one is the true final result.
+    async for mode, chunk in graph.astream(inputs, stream_mode=["updates", "values"]):
+        if mode == "updates":
+            for node, delta in chunk.items():
+                typer.secho(f"  → {node}: {delta}", fg=typer.colors.CYAN)
+        else:
+            final = chunk
+    return dict(final)
+
+
+@contextmanager
+def _local_identity() -> Iterator[None]:
+    """Bind a dev/local caller identity so the SDK clients' header builder has a context."""
+    token = set_caller_identity(
+        LLMCallerIdentity(
+            entity_id="local-dev",
+            stage_id="",  # Stage tier retired (FDP-2071) — field kept by the lib, value unused
+            workspace_id="local-dev",
+            correlation_id="cli-run",
+            agent_id="local-cli",
+            agent_version="1",
+        )
+    )
+    try:
+        yield
+    finally:
+        reset_caller_identity(token)
+
+
+@contextmanager
+def _offline_clients() -> Iterator[None]:
+    """Patch the SDK clients' transport so building-block calls return canned stubs (no network).
+
+    Imported lazily so ``validate`` (and online ``run``) don't pull the client/httpx stack.
+    """
+    from keystone.agent_sdk.clients import _base
+
+    async def _stub_post(self: Any, path: str, body: dict[str, Any], *, operation: str) -> dict[str, Any]:
+        typer.secho(f"  [offline] {operation} {path}", fg=typer.colors.YELLOW)
+        return _OFFLINE_STUBS.get(operation, {})
+
+    original = _base.BaseClient._post
+    _base.BaseClient._post = _stub_post  # type: ignore[method-assign]
+    try:
+        yield
+    finally:
+        _base.BaseClient._post = original  # type: ignore[method-assign]

keystone_cli/scaffold.py

@@ -0,0 +1,81 @@
+"""Project scaffolding for ``keystone agent init`` (FDP-3440 / US-3b).
+
+Templates ship as PACKAGE DATA (``keystone_cli/templates/<name>/**/*.tmpl``) — embedded,
+never fetched from the network (corporate-proxy-proof, unlike ``langgraph new``). Files
+render with plain placeholder substitution (no template engine): ``__AGENT_NAME__``,
+``__PKG__`` (name with ``-`` → ``_``), ``__WORKSPACE__``. The generated project follows
+the platform layout the SDK loader expects (flat ``<pkg>/graph.py`` next to ``agent.yaml``
+— what ``validate()`` puts on ``sys.path``) and passes ``keystone agent validate`` +
+``keystone agent run . --offline`` out of the box (CI-tested per template).
+"""
+
+from __future__ import annotations
+
+import re
+from importlib import resources
+from pathlib import Path
+
+TEMPLATES = ("blank", "llm", "rag-qa", "tool-agent", "hitl")
+
+# Agent names double as k8s child-resource names + queue names — keep them DNS-label-safe.
+_NAME_RE = re.compile(r"^[a-z][a-z0-9-]{1,62}$")
+
+# Template files stored dot-less and written out WITH the dot. Keep this in sync with the template
+# dirs — a name missing here lands in the project as `env` instead of `.env`, which the runtime never
+# reads and .gitignore never covers, so the key would end up committed.
+_DOTFILES = frozenset({"gitignore", "env"})
+
+
+class ScaffoldError(ValueError):
+    """User-facing scaffold failure (bad name/template, target dir not empty)."""
+
+
+def scaffold(name: str, template: str, dest_root: Path, workspace: str) -> Path:
+    """Render ``template`` into ``dest_root/<name>/``; returns the project dir."""
+    if not _NAME_RE.match(name):
+        raise ScaffoldError(
+            f"agent name {name!r} must be kebab-case (lowercase letters, digits, '-'; start with a letter)"
+        )
+    if template not in TEMPLATES:
+        raise ScaffoldError(f"unknown template {template!r} — choose one of: {', '.join(TEMPLATES)}")
+    dest = dest_root / name
+    if dest.exists() and any(dest.iterdir()):
+        raise ScaffoldError(f"target directory {dest} exists and is not empty — refusing to overwrite")
+
+    pkg = name.replace("-", "_")
+    replacements = {"__AGENT_NAME__": name, "__PKG__": pkg, "__WORKSPACE__": workspace}
+    root = resources.files("keystone_cli").joinpath("templates", template)
+
+    for src in _walk(root):
+        rel = _relative_parts(src, root)
+        # `pkg/` in the template becomes the agent's real package dir. Dotfiles are stored WITHOUT
+        # the leading dot (`gitignore.tmpl`, `env.tmpl`) and renamed here — a real dotfile inside the
+        # package data vanishes from sdists/wheels, so the template would ship without it.
+        parts = [pkg if p == "pkg" else p for p in rel]
+        filename = parts[-1].removesuffix(".tmpl")
+        if filename in _DOTFILES:
+            filename = f".{filename}"
+        out = dest.joinpath(*parts[:-1], filename)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        text = src.read_text(encoding="utf-8")
+        for placeholder, value in replacements.items():
+            text = text.replace(placeholder, value)
+        out.write_text(text, encoding="utf-8")
+    return dest
+
+
+def _walk(node):  # Traversable has no rglob — two levels is all the templates use
+    for child in node.iterdir():
+        if child.is_dir():
+            yield from _walk(child)
+        elif child.name.endswith(".tmpl"):
+            yield child
+
+
+def _relative_parts(src, root) -> list[str]:
+    """Path parts of ``src`` under ``root`` (Traversable-safe — compare by name chain)."""
+    # importlib Traversables expose no relative_to; templates are at most 2 levels deep,
+    # so rebuild the chain from the string forms (stable for both zip + dir loaders).
+    src_s, root_s = str(src), str(root)
+    rel = src_s[len(root_s) :].lstrip("/\\")
+    return rel.replace("\\", "/").split("/")

keystone_cli/templates/blank/README.md.tmpl

@@ -0,0 +1,25 @@
+# __AGENT_NAME__
+
+Keystone pro-code agent (scaffolded from the **blank** template).
+
+## Local loop
+```bash
+keystone agent validate .
+keystone dev . --input '{"message": "hi"}' --offline        # iterate: edit → Enter → new behaviour
+keystone agent run . --input '{"message": "hi"}' --offline   # mocked building blocks
+```
+
+## Deploy (dev)
+```bash
+keystone login                       # once per session (device flow)
+keystone agent deploy . --publish    # bundle → server-side build → Live
+keystone agent invoke __AGENT_NAME__ --input '{"message": "hi"}'
+```
+
+## Next steps
+- Real nodes: plain LangGraph (`add_node` / `add_edge` / `add_conditional_edges`).
+- Building blocks: `from keystone.agent_sdk.clients import RAGClient, GatewayClient`.
+- Long steps: wrap paid/side-effecting calls in `@durable_task` (crash-safe replay).
+- Human approval: `from keystone.agent_sdk import request_approval` (HITL pause/resume).
+- Rebuilds: agent-hub dedups identical bundles — bump the `# bundle-rev:` line in
+  `agent.yaml` to force a new image.

keystone_cli/templates/blank/agent.yaml.tmpl

@@ -0,0 +1,20 @@
+# bundle-rev: 0001 — bump this string to force a rebuild (agent-hub dedups identical bundles by SHA-256)
+# __AGENT_NAME__ — scaffolded by `keystone agent init` (template: blank).
+# Local loop:
+#   keystone agent validate .
+#   keystone agent run . --input '{"message": "hi"}' --offline
+# Deploy (server-side build — no Dockerfile needed):
+#   keystone agent deploy . --publish
+name: __AGENT_NAME__
+workspace: __WORKSPACE__
+framework: langgraph@1
+entrypoint: __PKG__.graph:make_graph
+runtime: python3.12
+resources:
+  timeout_seconds: 60
+io_schema:
+  type: object
+  properties:
+    message:
+      type: string
+  required: [message]

keystone_cli/templates/blank/env.tmpl

@@ -0,0 +1,10 @@
+# Local-only environment for `__AGENT_NAME__`. NEVER committed (.gitignore) and NEVER packaged —
+# `keystone agent deploy` drops .env* unconditionally, because a bundle goes to S3 and into the
+# agent's image in ECR, where a copy would outlive a revoked key.
+#
+# On the cluster the operator injects these, so leave them empty here unless you run locally.
+
+# The agent's platform API key. Create it on the portal (Access policy → API keys) and paste the
+# value shown ONCE. Read automatically: agent-runtime settings use env_prefix="RT_" + env_file=".env",
+# so the RT_ prefix is required — a differently-named variable is IGNORED SILENTLY.
+RT_AGENT_API_KEY=

keystone_cli/templates/blank/gitignore.tmpl

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+# Secrets + local config. Also excluded from the deploy bundle unconditionally.
+.env
+.env.*

keystone_cli/templates/blank/pkg/graph.py.tmpl

@@ -0,0 +1,33 @@
+"""__AGENT_NAME__ — a minimal Keystone pro-code agent.
+
+One-node LangGraph: ``respond`` echoes the input. Authoring is PLAIN LangGraph (the SDK
+wraps nothing); building-block clients (rag, llm-gateway) live in
+``keystone.agent_sdk.clients`` — see the rag-qa / tool-agent templates for examples.
+
+Local loop:
+    keystone agent validate .
+    keystone agent run . --input '{"message": "hi"}' --offline
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+from langgraph.graph import StateGraph
+
+
+class State(TypedDict, total=False):
+    message: str
+    reply: str
+
+
+def respond(state: State) -> dict[str, str]:
+    return {"reply": f"__AGENT_NAME__ received: {state.get('message', '')}"}
+
+
+def make_graph():
+    g = StateGraph(State)
+    g.add_node("respond", respond)
+    g.set_entry_point("respond")
+    g.set_finish_point("respond")
+    return g

keystone_cli/templates/blank/pyproject.toml.tmpl

@@ -0,0 +1,12 @@
+[project]
+name = "__AGENT_NAME__"
+version = "0.1.0"
+requires-python = ">=3.12"
+# Declared for humans/IDEs: the DEPLOYED image is built FROM the platform base image,
+# which already bakes keystone-agent-sdk + langgraph — the server-side (Kaniko) build
+# copies your code only, it does NOT pip-install. Locally, `keystone agent validate/run`
+# execute in the CLI's own environment.
+dependencies = [
+    "keystone-agent-sdk>=0.3",
+    "langgraph>=1,<2",
+]

keystone_cli/templates/hitl/README.md.tmpl

@@ -0,0 +1,33 @@
+# __AGENT_NAME__
+
+Scaffolded from the **hitl** template — a human-in-the-loop agent. It drafts a response and,
+when the request looks high-impact, **pauses for a person to approve** before releasing it.
+
+```
+__PKG__/graph.py   # assess → (approve | release);  approve calls request_approval(...)
+agent.yaml         # llm-gateway + a hitl: block (timeout, on_timeout);  io_schema = { request }
+```
+
+## Run it locally
+
+```bash
+keystone agent validate .
+keystone agent run . --input '{"request": "summarise today’s standup"}' --offline
+```
+
+Offline the model stub classifies every request as routine, so the run completes without
+pausing (a local run has no checkpointer to park on). The approval path is exercised on the
+platform.
+
+## Deploy and approve
+
+```bash
+keystone agent deploy . --publish
+keystone agent invoke __AGENT_NAME__ --input '{"request": "issue a $50 refund to order 1234"}'
+#   … awaiting_human (run <id>)
+keystone agent hitl list __AGENT_NAME__
+keystone agent hitl respond __AGENT_NAME__ <run-id> --approve --note "ok"
+```
+
+Use `--reject` to send it down the declined branch instead. See `examples/getting-started.html`
+for the full flow and the `demo-helpdesk` / `support-triage` examples for richer HITL graphs.

keystone_cli/templates/hitl/agent.yaml.tmpl

@@ -0,0 +1,33 @@
+# bundle-rev: 0001 — bump this string to force a rebuild (agent-hub dedups identical bundles by SHA-256)
+# __AGENT_NAME__ — scaffolded by `keystone agent init` (template: hitl).
+# Drafts a response, then PAUSES for a human to approve high-impact requests before releasing them.
+# Local loop (offline stub classifies low-impact → runs straight through, no pause):
+#   keystone agent validate .
+#   keystone agent run . --input '{"request": "summarise today’s standup"}' --offline
+# Deploy (server-side build — no Dockerfile needed):
+#   keystone agent deploy . --publish
+name: __AGENT_NAME__
+workspace: __WORKSPACE__
+framework: langgraph@1
+entrypoint: __PKG__.graph:make_graph
+runtime: python3.12
+resources:
+  timeout_seconds: 60
+# Human-in-the-loop: a paused run waits this long for an approver, then takes on_timeout.
+# `reject` flows the graph's own declined branch (a dead `expired` run would be worse UX).
+hitl:
+  timeout_seconds: 3600
+  on_timeout: reject
+io_schema:
+  type: object
+  properties:
+    request:
+      type: string
+  required: [request]
+dependencies:
+  services: [llm-gateway]
+  models: [bedrock/anthropic.claude-sonnet-4-6]
+identity:
+  scopes: [gateway:chat]
+config:
+  RT_AGENT_MODEL: "bedrock/anthropic.claude-sonnet-4-6"

keystone_cli/templates/hitl/env.tmpl

@@ -0,0 +1,10 @@
+# Local-only environment for `__AGENT_NAME__`. NEVER committed (.gitignore) and NEVER packaged —
+# `keystone agent deploy` drops .env* unconditionally, because a bundle goes to S3 and into the
+# agent's image in ECR, where a copy would outlive a revoked key.
+#
+# On the cluster the operator injects these, so leave them empty here unless you run locally.
+
+# The agent's platform API key. Create it on the portal (Access policy → API keys) and paste the
+# value shown ONCE. Read automatically: agent-runtime settings use env_prefix="RT_" + env_file=".env",
+# so the RT_ prefix is required — a differently-named variable is IGNORED SILENTLY.
+RT_AGENT_API_KEY=

keystone_cli/templates/hitl/gitignore.tmpl

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+# Secrets + local config. Also excluded from the deploy bundle unconditionally.
+.env
+.env.*

keystone_cli/templates/hitl/pkg/graph.py.tmpl

@@ -0,0 +1,115 @@
+"""__AGENT_NAME__ — human-in-the-loop: draft a response, then pause for approval when it matters.
+
+    assess ──high-impact?──▶ approve ──human says yes──▶ release the draft
+                        │                └──says no────▶ declined note
+                        └──routine───────────────────▶ release the draft
+
+``assess`` drafts the response AND asks the model whether the request is high-impact. A
+**conditional edge** routes high-impact requests through ``approve``, which calls
+``request_approval`` — the run parks as ``awaiting_human`` until a person answers with
+``keystone agent hitl respond``. Routine requests skip straight to release.
+
+Two rules the platform enforces for HITL (see keystone.agent_sdk.request_approval):
+  * Call ``request_approval`` EARLY in the node — on resume the whole node re-runs up to it,
+    so nothing paid/side-effecting may run before it. Here it is the first statement.
+  * Paid work goes through ``@durable_task`` so a crash-resume replays it, never re-bills it.
+
+Offline the model stub isn't valid JSON, so ``assess`` defaults to routine and the run
+completes without ever pausing (a local run has no checkpointer to park on).
+
+Local loop:
+    keystone agent run . --input '{"request": "summarise today’s standup"}' --offline
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, TypedDict
+
+from keystone.agent_sdk import durable_task, request_approval
+from keystone.agent_sdk.clients import GatewayClient
+from langgraph.graph import StateGraph
+
+
+class State(TypedDict, total=False):
+    request: str  # what the user asked the agent to do (the input)
+    draft: str  # the response the agent proposes
+    needs_approval: bool  # true → route through a human before releasing
+    result: str  # the released response (or the declined note)
+    approved: bool
+
+
+def _gateway() -> GatewayClient:
+    return GatewayClient(
+        base_url=os.environ.get("RT_GATEWAY_URL", ""),
+        auth_token=os.environ.get("RT_GATEWAY_TOKEN", ""),
+    )
+
+
+def _model() -> str:
+    return os.environ.get("RT_AGENT_MODEL", "bedrock/anthropic.claude-sonnet-4-6")
+
+
+@durable_task
+async def _chat(system: str, user: str) -> str:
+    # The paid step. @durable_task: a crash-resumed run replays the persisted answer
+    # instead of paying for the model twice. Plain-data args only — client built inside.
+    result = await _gateway().chat(
+        messages=[
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ],
+        model=_model(),
+    )
+    return result["choices"][0]["message"]["content"] if isinstance(result, dict) else ""
+
+
+async def assess(state: State) -> dict[str, Any]:
+    """Draft the response, and classify whether it needs a human sign-off before release."""
+    request = state.get("request", "")
+    draft = await _chat("You are a helpful assistant. Write a short, ready-to-send response.", request)
+    raw = await _chat(
+        'Reply with ONLY {"high_impact": true|false} — true if carrying out this request could '
+        "spend money, message a customer, or change data. No prose, no code fences.",
+        request,
+    )
+    needs = False
+    try:
+        needs = bool(json.loads(raw).get("high_impact", False))
+    except (json.JSONDecodeError, TypeError):
+        pass  # unparseable (or the offline stub) → treat as routine, never crash
+    return {"draft": draft, "needs_approval": needs}
+
+
+def _route(state: State) -> str:
+    return "approve" if state.get("needs_approval") else "release"
+
+
+async def approve(state: State) -> dict[str, Any]:
+    # request_approval MUST be first — the node re-runs to here on resume. The run parks as
+    # awaiting_human; the approver's dict comes back when they respond.
+    decision = request_approval(
+        {"kind": "release_approval", "request": state.get("request", ""), "draft": state.get("draft", "")}
+    )
+    approved = bool(decision.get("approved")) if isinstance(decision, dict) else False
+    if not approved:
+        note = decision.get("note", "") if isinstance(decision, dict) else ""
+        return {"result": note or "Declined by the approver.", "approved": False}
+    return {"result": state.get("draft", ""), "approved": True}
+
+
+def release(state: State) -> dict[str, Any]:
+    return {"result": state.get("draft", ""), "approved": True}
+
+
+def make_graph():
+    g = StateGraph(State)
+    g.add_node("assess", assess)
+    g.add_node("approve", approve)
+    g.add_node("release", release)
+    g.set_entry_point("assess")
+    g.add_conditional_edges("assess", _route, {"approve": "approve", "release": "release"})
+    g.set_finish_point("approve")
+    g.set_finish_point("release")
+    return g

keystone_cli/templates/hitl/pyproject.toml.tmpl

@@ -0,0 +1,12 @@
+[project]
+name = "__AGENT_NAME__"
+version = "0.1.0"
+requires-python = ">=3.12"
+# Declared for humans/IDEs: the DEPLOYED image is built FROM the platform base image,
+# which already bakes keystone-agent-sdk + langgraph — the server-side (Kaniko) build
+# copies your code only, it does NOT pip-install. Locally, `keystone agent validate/run`
+# execute in the CLI's own environment.
+dependencies = [
+    "keystone-agent-sdk>=0.3",
+    "langgraph>=1,<2",
+]

keystone_cli/templates/llm/README.md.tmpl

@@ -0,0 +1,29 @@
+# __AGENT_NAME__
+
+Scaffolded from the **llm** template — the simplest useful agent: one node that calls the
+model through **llm-gateway** and returns its reply. No knowledge base, no tools.
+
+```
+__PKG__/graph.py   # respond: GatewayClient.chat(...) → reply
+agent.yaml         # declares llm-gateway + the model; io_schema = { prompt }
+```
+
+## Run it locally
+
+```bash
+keystone agent validate .
+keystone agent run . --input '{"prompt": "explain retries in one sentence"}' --offline
+```
+
+`--offline` mocks the gateway call so you can prove the wiring with no live services or quota.
+Drop `--offline` (after `keystone login`) to hit the real model.
+
+## Deploy
+
+```bash
+keystone agent deploy . --publish
+keystone agent invoke __AGENT_NAME__ --input '{"prompt": "..."}'
+```
+
+The model in `dependencies.models` must be granted to your workspace, or deploy fails preflight
+with `422 AGENT_DEPENDENCY_NOT_GRANTED`. See `examples/getting-started.html` for the full flow.

keystone_cli/templates/llm/agent.yaml.tmpl

@@ -0,0 +1,29 @@
+# bundle-rev: 0001 — bump this string to force a rebuild (agent-hub dedups identical bundles by SHA-256)
+# __AGENT_NAME__ — scaffolded by `keystone agent init` (template: llm).
+# The simplest useful agent: one node that calls the LLM through llm-gateway and returns its reply.
+# Local loop:
+#   keystone agent validate .
+#   keystone agent run . --input '{"prompt": "explain retries in one sentence"}' --offline
+# Deploy (server-side build — no Dockerfile needed):
+#   keystone agent deploy . --publish
+name: __AGENT_NAME__
+workspace: __WORKSPACE__
+framework: langgraph@1
+entrypoint: __PKG__.graph:make_graph
+runtime: python3.12
+resources:
+  timeout_seconds: 60
+io_schema:
+  type: object
+  properties:
+    prompt:
+      type: string
+  required: [prompt]
+dependencies:
+  services: [llm-gateway]
+  models: [bedrock/anthropic.claude-sonnet-4-6]
+identity:
+  scopes: [gateway:chat]
+# Per-agent config — injected into the pod as env by the operator.
+config:
+  RT_AGENT_MODEL: "bedrock/anthropic.claude-sonnet-4-6"

keystone_cli/templates/llm/env.tmpl

@@ -0,0 +1,10 @@
+# Local-only environment for `__AGENT_NAME__`. NEVER committed (.gitignore) and NEVER packaged —
+# `keystone agent deploy` drops .env* unconditionally, because a bundle goes to S3 and into the
+# agent's image in ECR, where a copy would outlive a revoked key.
+#
+# On the cluster the operator injects these, so leave them empty here unless you run locally.
+
+# The agent's platform API key. Create it on the portal (Access policy → API keys) and paste the
+# value shown ONCE. Read automatically: agent-runtime settings use env_prefix="RT_" + env_file=".env",
+# so the RT_ prefix is required — a differently-named variable is IGNORED SILENTLY.
+RT_AGENT_API_KEY=

keystone_cli/templates/llm/gitignore.tmpl

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+# Secrets + local config. Also excluded from the deploy bundle unconditionally.
+.env
+.env.*

keystone_cli/templates/llm/pkg/graph.py.tmpl

@@ -0,0 +1,53 @@
+"""__AGENT_NAME__ — a minimal llm-gateway agent: one node that calls the model.
+
+Authoring is PLAIN LangGraph — the SDK wraps nothing. The only building block here is
+``GatewayClient`` (``keystone.agent_sdk.clients``): every model call in the platform goes
+through llm-gateway, which enforces the workspace's model grants and budget. Caller identity
+(entity / user / workspace) is forwarded automatically by the runtime — the agent never sets
+headers itself. The model + gateway URL come from ENV, injected per-agent by the operator.
+
+Local loop:
+    keystone agent run . --input '{"prompt": "explain retries in one sentence"}' --offline
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TypedDict
+
+from keystone.agent_sdk.clients import GatewayClient
+from langgraph.graph import StateGraph
+
+_SYSTEM = "You are a concise, helpful assistant. Answer in a few sentences."
+
+
+class State(TypedDict, total=False):
+    prompt: str
+    reply: str
+
+
+def _gateway() -> GatewayClient:
+    return GatewayClient(
+        base_url=os.environ.get("RT_GATEWAY_URL", ""),
+        auth_token=os.environ.get("RT_GATEWAY_TOKEN", ""),
+    )
+
+
+async def respond(state: State) -> dict[str, str]:
+    result = await _gateway().chat(
+        messages=[
+            {"role": "system", "content": _SYSTEM},
+            {"role": "user", "content": state.get("prompt", "")},
+        ],
+        model=os.environ.get("RT_AGENT_MODEL", "bedrock/anthropic.claude-sonnet-4-6"),
+    )
+    reply = result["choices"][0]["message"]["content"] if isinstance(result, dict) else ""
+    return {"reply": reply}
+
+
+def make_graph():
+    g = StateGraph(State)
+    g.add_node("respond", respond)
+    g.set_entry_point("respond")
+    g.set_finish_point("respond")
+    return g

keystone_cli/templates/llm/pyproject.toml.tmpl

@@ -0,0 +1,12 @@
+[project]
+name = "__AGENT_NAME__"
+version = "0.1.0"
+requires-python = ">=3.12"
+# Declared for humans/IDEs: the DEPLOYED image is built FROM the platform base image,
+# which already bakes keystone-agent-sdk + langgraph — the server-side (Kaniko) build
+# copies your code only, it does NOT pip-install. Locally, `keystone agent validate/run`
+# execute in the CLI's own environment.
+dependencies = [
+    "keystone-agent-sdk>=0.3",
+    "langgraph>=1,<2",
+]