keystone-cli 0.3.0__tar.gz → 0.4.0__tar.gz

keystone_cli-0.4.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: keystone-cli
+Version: 0.4.0
+Summary: Keystone CLI — build, test, deploy and operate pro-code agents, and manage knowledge bases, prompts, tool credentials and skills on the Keystone platform.
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: keystone-agent-sdk<0.14,>=0.13.20
+Requires-Dist: keystone-request-context<0.4,>=0.3
+Requires-Dist: typer<1,>=0.12
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: truststore<1,>=0.10
+Requires-Dist: pytest<9,>=8
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Requires-Dist: pytest-cov<7,>=6; extra == "dev"
+Requires-Dist: ruff==0.15.15; extra == "dev"
+
+# keystone-cli
+
+`keystone` is the command-line tool of the Keystone platform. Use it to build, test, deploy and operate
+pro-code agents. You can also manage knowledge bases, prompts, tool credentials and skills with it.
+
+The CLI includes the Keystone agent SDK (`keystone-agent-sdk`). An agent project that you create with
+the CLI uses that SDK.
+
+## Install
+
+The CLI needs Python 3.12 or later.
+
+```bash
+pip install keystone-cli
+keystone --version
+```
+
+## Get started
+
+1. Log in. The command opens your browser and keeps your session for later commands.
+
+   ```bash
+   keystone login
+   ```
+
+2. Select the workspace that your commands use.
+
+   ```bash
+   keystone workspace use <name>
+   ```
+
+3. Create an agent project from a template, then check it.
+
+   ```bash
+   keystone agent init my-agent --template llm
+   keystone agent validate my-agent
+   ```
+
+4. Run the unit tests of the agent on your computer.
+
+   ```bash
+   keystone agent test my-agent
+   ```
+
+5. Deploy the agent, make the new version Live, and call it.
+
+   ```bash
+   keystone agent deploy my-agent --publish --wait
+   keystone agent invoke my-agent --input '{"prompt": "hi"}'
+   ```
+
+To see the fields of `agent.yaml`, run `keystone agent manifest`. Every command has `--help`.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `keystone login`, `keystone whoami` | Log in, and show your user. |
+| `keystone workspace` | List and select the workspace that your commands use. |
+| `keystone agent` | Develop and test an agent locally (`init`, `validate`, `run`, `test`, `manifest`), ship it (`deploy`, `publish`, `status`, `retire`, `delete`), and operate and debug it (`invoke`, `logs`, `fetch`, `doctor`, `runs`, `hitl`, `traces`, `threads`). |
+| `keystone dev` | Run the graph of the agent locally again each time you save a file. |
+| `keystone kb` | Create and manage knowledge bases. |
+| `keystone prompt` | Manage the prompts of a workspace. |
+| `keystone tool-credentials` | Manage the credentials that the catalogue tools of your agents use. |
+| `keystone skills` | Install Claude Code skills for work on agents. |
+| `keystone version` | Show the CLI version, the target environment and the version of the bundled agent SDK. |
+
+## When a run fails
+
+Start with this command. It shows the steps, the errors and the logs of one run.
+
+```bash
+keystone agent runs debug <agent> <run_id>
+```

keystone_cli-0.4.0/README.md

@@ -0,0 +1,74 @@
+# keystone-cli
+
+`keystone` is the command-line tool of the Keystone platform. Use it to build, test, deploy and operate
+pro-code agents. You can also manage knowledge bases, prompts, tool credentials and skills with it.
+
+The CLI includes the Keystone agent SDK (`keystone-agent-sdk`). An agent project that you create with
+the CLI uses that SDK.
+
+## Install
+
+The CLI needs Python 3.12 or later.
+
+```bash
+pip install keystone-cli
+keystone --version
+```
+
+## Get started
+
+1. Log in. The command opens your browser and keeps your session for later commands.
+
+   ```bash
+   keystone login
+   ```
+
+2. Select the workspace that your commands use.
+
+   ```bash
+   keystone workspace use <name>
+   ```
+
+3. Create an agent project from a template, then check it.
+
+   ```bash
+   keystone agent init my-agent --template llm
+   keystone agent validate my-agent
+   ```
+
+4. Run the unit tests of the agent on your computer.
+
+   ```bash
+   keystone agent test my-agent
+   ```
+
+5. Deploy the agent, make the new version Live, and call it.
+
+   ```bash
+   keystone agent deploy my-agent --publish --wait
+   keystone agent invoke my-agent --input '{"prompt": "hi"}'
+   ```
+
+To see the fields of `agent.yaml`, run `keystone agent manifest`. Every command has `--help`.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `keystone login`, `keystone whoami` | Log in, and show your user. |
+| `keystone workspace` | List and select the workspace that your commands use. |
+| `keystone agent` | Develop and test an agent locally (`init`, `validate`, `run`, `test`, `manifest`), ship it (`deploy`, `publish`, `status`, `retire`, `delete`), and operate and debug it (`invoke`, `logs`, `fetch`, `doctor`, `runs`, `hitl`, `traces`, `threads`). |
+| `keystone dev` | Run the graph of the agent locally again each time you save a file. |
+| `keystone kb` | Create and manage knowledge bases. |
+| `keystone prompt` | Manage the prompts of a workspace. |
+| `keystone tool-credentials` | Manage the credentials that the catalogue tools of your agents use. |
+| `keystone skills` | Install Claude Code skills for work on agents. |
+| `keystone version` | Show the CLI version, the target environment and the version of the bundled agent SDK. |
+
+## When a run fails
+
+Start with this command. It shows the steps, the errors and the logs of one run.
+
+```bash
+keystone agent runs debug <agent> <run_id>
+```

{keystone_cli-0.3.0 → keystone_cli-0.4.0}/pyproject.toml

@@ -4,13 +4,23 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "keystone-cli"
-version = "0.3.0"
-description = "Keystone pro-code agent CLI — build, test, deploy and operate agents on the Keystone platform."
+version = "0.4.0"
+description = "Keystone CLI — build, test, deploy and operate pro-code agents, and manage knowledge bases, prompts, tool credentials and skills on the Keystone platform."
+# The PyPI project page shows this file (it had no description before 0.4.0). It is public: no internal
+# hosts, entity ids or workspace ids in it.
+readme = "README.md"
 requires-python = ">=3.12"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+]
 dependencies = [
     # Pinned to a compatible range: on an index (Artifact Registry) an unpinned name resolves to
     # ANY published version — the wheel's metadata is the only pin that travels with it.
-    "keystone-agent-sdk>=0.13.10,<0.14",
+    # 0.4.0 needs 0.13.20: the file client of FDP-6964 and the A2UI chat blocks of FDP-7060.
+    "keystone-agent-sdk>=0.13.20,<0.14",
     # Transitive (the SDK's building-block clients) + used directly by `run` to set a local
     # caller-identity ContextVar and to patch the clients for --offline. uv sources are NOT
     # transitive, so declare it directly (cf. services/llm-gateway).
@@ -34,8 +44,8 @@ dev = [
 ]
 
 # The `keystone` command (binary) — `typer.Typer` instances are callable, so the entry points
-# straight at the app. Distributed later via an internal index (packaging task); M1 installs
-# from the repo path (`uv tool install ./libs/python/keystone-cli`).
+# straight at the app. Published to PyPI as `keystone-cli` (prod) and to Artifact Registry per env
+# (`keystone-cli-<env>`); from the repo: `uv tool install ./libs/python/keystone-cli`.
 [project.scripts]
 keystone = "keystone_cli.__main__:app"
 
@@ -51,7 +61,7 @@ where = ["src"]
 keystone_cli = ["templates/*/*.tmpl", "templates/*/pkg/*.tmpl", "templates/*/tests/*.tmpl", "skills/*/SKILL.md"]
 
 [tool.ruff]
-target-version = "0.3.0"
+target-version = "0.4.0"
 line-length = 120
 
 [tool.ruff.lint]

{keystone_cli-0.3.0 → keystone_cli-0.4.0}/src/keystone_cli/__main__.py

@@ -61,7 +61,10 @@ Exit codes:
   on stdout and the message on stderr."""
 
 app = typer.Typer(
-    help="Keystone CLI — build, test, deploy and operate pro-code agents.",
+    help=(
+        "Keystone CLI — build, test, deploy and operate pro-code agents, and manage knowledge bases, "
+        "prompts, tool credentials and skills."
+    ),
     epilog=EPILOG,
     no_args_is_help=True,
     add_completion=False,

{keystone_cli-0.3.0 → keystone_cli-0.4.0}/src/keystone_cli/commands/agent.py

@@ -2964,6 +2964,12 @@ _GRANT_NAMESPACE = {
     # `ocr` once platform v112 is on the env. An agent published before that holds none until it
     # is re-published.
     "ocr": "ocr:",
+    # Sprint: v8 | Feature: FR-157 OCR in the Pro-code Agent SDK | Task Group: 1.4 | ACs: AC-1240
+    # Contract: agent-hub AgentManifestAclGrants FILE_ARTIFACT_PERMISSIONS | Tracking: FDP-6120
+    # agent-hub mints artifact:create + artifact:read on the workspace from `file-artifact` (FDP-6261),
+    # and an agent that reads a file by reference must declare it (FR-157 AC-08). Without this entry
+    # doctor called it a typo and exited 1 while every call to it worked (FDP-6120 QC, qc 24-10).
+    "file-artifact": "artifact:",
 }
 #: Every name agent-hub acts on (AgentManifestAclGrants): the ones above plus rag, whose access is
 #: the per-KB grant instead of a service-level one. Anything else mints nothing and is not in the

{keystone_cli-0.3.0 → keystone_cli-0.4.0}/src/keystone_cli/runner.py

@@ -458,9 +458,52 @@ _OFFLINE_STUBS: dict[str, dict[str, Any]] = {
     ),
     # OCR (FDP-5712) — every OcrClient operation. Enveloped like the service; `ocr_list_pages`
     # keeps `pagination` beside `data`.
+    # Data Space (FDP-6473) — a SQL space's /ask body, unwrapped (the service sends no envelope).
+    "data_space_ask": {
+        "sql": "SELECT 1 AS offline_stub",
+        "columns": ["offline_stub"],
+        "rows": [[1]],
+        "row_count": 1,
+        "source_tables": [],
+        "trace": [],
+        "ambiguities": [],
+    },
     "ocr_sync_from_url": _enveloped({"pages": [_OFFLINE_OCR_PAGE], "summary": _OFFLINE_OCR_SUMMARY}),
     "ocr_submit_job_from_url": _enveloped({**_OFFLINE_OCR_JOB, "status": "queued", "completed_at": None}),
+    # A file-artifact reference (FDP-6120): the same answers, the job's `source` naming what was read.
+    "ocr_sync_from_artifact": _enveloped({"pages": [_OFFLINE_OCR_PAGE], "summary": _OFFLINE_OCR_SUMMARY}),
+    "ocr_submit_job_from_artifact": _enveloped(
+        {
+            **_OFFLINE_OCR_JOB,
+            "status": "queued",
+            "completed_at": None,
+            "source": {"type": "file_artifact", "artifact_id": "offline-artifact", "version": 1, "sha256": "0" * 64},
+        }
+    ),
     "ocr_get_job": _enveloped(_OFFLINE_OCR_JOB),
+    # The user's attachments (FDP-6261). An offline turn carries none, so these answer only a call
+    # an author makes by hand; the shapes are file-artifact's `get_metadata` and `read_artifact`.
+    "file_artifact_get_attachment": _enveloped(
+        {
+            "artifact_id": "offline-artifact",
+            "name": "offline.txt",
+            "mime": "text/plain",
+            "size_bytes": 27,
+            "status": "ACTIVE",
+            "purpose": "attachment",
+        }
+    ),
+    "file_artifact_read_attachment": _enveloped(
+        {"artifact_id": "offline-artifact", "version": 1, "mime": "text/plain", "text": "[offline attachment text]"}
+    ),
+    "file_artifact_attachment_url": _enveloped(
+        {"artifact_id": "offline-artifact", "download_url": "https://offline.invalid/offline-artifact"}
+    ),
+    # Speech-to-text (FDP-6261): an audio attachment's transcript, short clip or long.
+    "audio_transcription": {"text": "[offline transcript]", "duration": 1.0},
+    "audio_transcription_job": {"id": "offline-stt-job", "status": "processing"},
+    "audio_transcription_job_get": {"id": "offline-stt-job", "status": "completed"},
+    "audio_transcription_transcript": {"text": "[offline transcript]"},
     "ocr_cancel_job": _enveloped({**_OFFLINE_OCR_JOB, "status": "cancelled"}),
     "ocr_read_text": _enveloped(
         {
@@ -640,7 +683,8 @@ def _local_identity() -> Iterator[None]:
 def _offline_clients() -> Iterator[None]:
     """Patch the SDK clients' transport so building-block calls return canned stubs (no network).
 
-    Patches **every verb** (``_post``, ``_get``, ``_patch``, ``_put``, ``_delete``, ``_post_multipart``).
+    Patches **every verb** (``_post``, ``_get``, ``_patch``, ``_put``, ``_delete``, ``_post_multipart``,
+    ``_get_bytes``).
     Missing one is not a partial feature: an
     unpatched verb reaches the real network from a mode whose whole promise is "no live services
     or quota", and it does so silently.
@@ -701,6 +745,11 @@ def _offline_clients() -> Iterator[None]:
     async def _stub_get(self: Any, path: str, *, operation: str, **_: Any) -> dict[str, Any]:
         return _stub(operation, path)
 
+    async def _stub_get_bytes(self: Any, path: str, *, operation: str, **_: Any) -> bytes:
+        # FDP-6261: an attachment's bytes. Without it a download left the pod.
+        typer.secho(f"  [offline] {operation} {path}", fg=typer.colors.YELLOW)
+        return b"[offline attachment bytes]"
+
     async def _stub_resolve(self: Any, name: str, **_: Any) -> Any:
         # FDP-6465: the prompt read is not a verb of BaseClient (it needs the ETag/304 path), so it
         # is patched on its own. An OUTAGE, not a stub version: aget_prompt then runs on the
@@ -718,6 +767,7 @@ def _offline_clients() -> Iterator[None]:
         _base.BaseClient._put,
         _base.BaseClient._delete,
         _base.BaseClient._post_multipart,
+        _base.BaseClient._get_bytes,
     )
     _base.BaseClient._post = _stub_post  # type: ignore[method-assign]
     _base.BaseClient._get = _stub_get  # type: ignore[method-assign]
@@ -725,6 +775,7 @@ def _offline_clients() -> Iterator[None]:
     _base.BaseClient._put = _stub_put  # type: ignore[method-assign]
     _base.BaseClient._delete = _stub_delete  # type: ignore[method-assign]
     _base.BaseClient._post_multipart = _stub_multipart  # type: ignore[method-assign]
+    _base.BaseClient._get_bytes = _stub_get_bytes  # type: ignore[method-assign]
     try:
         yield
     finally:
@@ -735,5 +786,6 @@ def _offline_clients() -> Iterator[None]:
             _base.BaseClient._put,
             _base.BaseClient._delete,
             _base.BaseClient._post_multipart,
+            _base.BaseClient._get_bytes,
         ) = originals  # type: ignore[method-assign]
         prompt_hub.PromptHubClient.resolve = original_resolve  # type: ignore[method-assign]

{keystone_cli-0.3.0 → keystone_cli-0.4.0}/src/keystone_cli/scaffold.py

@@ -40,6 +40,11 @@ TEMPLATES = (
     "kb-builder",
     # FDP-5712 — OCR a document by signed URL (sync, or as a job read back as text).
     "ocr",
+    # FDP-6473 — what an agent does for the END USER of a chat turn: draw a UI component and
+    # answer its click, ask a data space as that person, call a tool with that person's sign-in.
+    "ui-card",
+    "data-space",
+    "user-tools",
 )
 
 # Agent names double as k8s child-resource names + queue names — keep them DNS-label-safe.

keystone_cli-0.4.0/src/keystone_cli/templates/data-space/README.md.tmpl

@@ -0,0 +1,53 @@
+# __AGENT_NAME__
+
+Scaffolded from the **data-space** template. The agent answers questions from one published
+Keystone Data Space, **as the end user of the turn**: the data space applies that person's access.
+
+## Set it up
+
+1. Publish a data space in your workspace, and copy its id.
+2. In `agent.yaml`, put the id in `dependencies.data_spaces` **and** in
+   `config.RT_AGENT_DATA_SPACE_ID`.
+   - `data_spaces` makes agent-hub grant the agent `data-space:read` and `data-space:query` on
+     the space at publish.
+   - `data-space-runtime` in `dependencies.services` scopes the invocation key to the data space
+     service. Do not remove it.
+3. Deploy: `keystone agent deploy . --publish`.
+
+## What the user sees
+
+- An answer: the summary (NDP space) and the first rows as a table.
+- **Sign-in needed**: when the space has an Access Grant and the user has not signed in with an
+  Auth Client that it accepts, `ask` raises `SignInRequired`. The graph calls
+  `request_sign_in(exc)`, and the chat shows the sign-in card. After the sign-in, the next
+  question can succeed.
+- **No access**: when the user is not in the space's Access Grant and no Auth Client can change
+  that, `ask` raises `BuildingBlockForbiddenError` (a `SignInRequired` is a subclass, so catch
+  that first). The agent tells the user. An uncaught error fails the run, and the Front Desk
+  master then shows "no answer".
+- A refusal that the space gives (it cannot plan the question, the space is not available): the
+  agent tells the user and does not retry. Each question costs a model call.
+
+## Known limits
+
+- The data space can run with the agent-grant check off (`DS_CONSUMER_ACCESS_ENFORCED`). In an
+  environment where it is off, a space that the manifest does not declare can still answer. Do
+  not rely on that: declare every space.
+
+## Local loop
+```bash
+keystone agent validate .
+keystone agent run . --input '{"messages": [{"role": "user", "content": "How many orders this month?"}]}' --offline
+keystone agent test .
+```
+
+`--offline` answers every question with a stub row; no data space is called.
+
+## Unit tests
+
+```bash
+keystone agent test .
+```
+
+`use_client("get_data_space_client", fake)` puts a fake in place of the data space. The fake
+needs only `ask`. Raise `SignInRequired` from it to test the sign-in path.

keystone_cli-0.4.0/src/keystone_cli/templates/data-space/agent.yaml.tmpl

@@ -0,0 +1,25 @@
+# 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: data-space).
+# A chat agent that answers questions from a Keystone Data Space, as the end user of the turn.
+# Local loop:
+#   keystone agent validate .
+#   keystone agent run . --input '{"messages": [{"role": "user", "content": "How many orders this month?"}]}' --offline
+#   keystone agent test
+name: __AGENT_NAME__
+workspace: __WORKSPACE__
+framework: langgraph@1
+entrypoint: __PKG__.graph:make_graph
+runtime: python3.12
+resources:
+  # One answer plans, runs and summarises a query: give it time.
+  timeout_seconds: 180
+dependencies:
+  # `data-space-runtime` scopes the run's invocation key to the data space service. Without it
+  # every ask is refused before it reaches the space.
+  services: [data-space-runtime]
+  # The PUBLISHED data spaces this agent asks (UUIDs). agent-hub grants the agent
+  # data-space:read + data-space:query on each one at publish. Replace the zero UUID with yours,
+  # here AND in config below.
+  data_spaces: ["00000000-0000-0000-0000-000000000000"]
+config:
+  RT_AGENT_DATA_SPACE_ID: "00000000-0000-0000-0000-000000000000"

keystone_cli-0.4.0/src/keystone_cli/templates/data-space/pkg/graph.py.tmpl

@@ -0,0 +1,120 @@
+"""__AGENT_NAME__ — answer from a Keystone Data Space, as the end user of the turn (FDP-6473).
+
+One node:
+
+1. Ask the published data space the user's question with ``DataSpaceClient.ask``. The call goes
+   through the platform gateway with the run's invocation key, so the data space sees the agent
+   AND the end user, and applies the end user's access.
+2. When the space has an Access Grant and the user has not signed in with an Auth Client it
+   accepts, ``ask`` raises ``SignInRequired``. Show the sign-in card with ``request_sign_in`` and
+   tell the user. Do not answer as though the space had no data.
+   Any other 403 (``BuildingBlockForbiddenError``: the user is not in the space's Access Grant and
+   no sign-in can change that, or the agent has no grant on the space) is told to the user too.
+   Catch ``SignInRequired`` first: it is a subclass. An uncaught error fails the run, and a
+   caller such as the Front Desk master then shows "no answer".
+3. A refusal that the space answers inside a normal reply (an unavailable space, a question it
+   cannot plan) is ``answer.error``: tell the user, do not retry. A question costs a model call.
+
+The state keeps the questions and their SQL in ``history``, so a follow-up question ("and last
+month?") is read in context. The data space reads the last 10 turns.
+
+Local loop:
+    keystone agent run . --input '{"messages": [{"role": "user", "content": "How many orders this month?"}]}' --offline
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Annotated, Any, TypedDict
+
+from keystone.agent_sdk.clients import (
+    BuildingBlockForbiddenError,
+    DataSpaceAnswer,
+    SignInRequired,
+    get_data_space_client,
+)
+from keystone.agent_sdk.ui import request_sign_in
+from langchain_core.messages import AIMessage, AnyMessage, HumanMessage
+from langgraph.graph import StateGraph
+from langgraph.graph.message import add_messages
+
+#: Rows shown in the chat. The answer keeps all of them in ``answer.rows``.
+MAX_ROWS = 10
+
+SIGN_IN_REPLY = "You must sign in to see this data. Use the sign-in card, then ask again."
+NO_ACCESS_REPLY = "You do not have access to this data space. Ask its owner for access."
+
+
+class State(TypedDict, total=False):
+    messages: Annotated[list[AnyMessage], add_messages]
+    # Earlier questions of this conversation, for follow-ups: [{"question", "sql"}].
+    history: list[dict[str, Any]]
+
+
+def _space_id() -> str:
+    space = os.environ.get("RT_AGENT_DATA_SPACE_ID", "").strip()
+    if not space:
+        raise RuntimeError("RT_AGENT_DATA_SPACE_ID is empty — set it under `config:` in agent.yaml")
+    return space
+
+
+def _question(state: State) -> str:
+    for message in reversed(state.get("messages") or []):
+        if isinstance(message, HumanMessage) and isinstance(message.content, str):
+            return message.content.strip()
+    return ""
+
+
+def format_answer(answer: DataSpaceAnswer) -> str:
+    """The answer as chat text: the summary (NDP space), then the first rows as a table."""
+    parts: list[str] = []
+    if answer.summary:
+        parts.append(answer.summary)
+    if answer.rows:
+        parts.append(_table(answer.columns, answer.rows[:MAX_ROWS]))
+        if len(answer.rows) > MAX_ROWS:
+            parts.append(f"(first {MAX_ROWS} of {len(answer.rows)} rows)")
+    if not parts:
+        parts.append("The data space found no rows for this question.")
+    return "\n\n".join(parts)
+
+
+def _table(columns: list[Any], rows: list[Any]) -> str:
+    # A SQL space sends rows as lists; an NDP space as objects.
+    names = [str(c.get("name") if isinstance(c, dict) else c) for c in columns]
+    if not names and rows and isinstance(rows[0], dict):
+        names = list(rows[0])
+    lines = ["| " + " | ".join(names) + " |", "|" + "---|" * len(names)]
+    for row in rows:
+        cells = [row.get(n) for n in names] if isinstance(row, dict) else list(row)
+        lines.append("| " + " | ".join("" if v is None else str(v) for v in cells) + " |")
+    return "\n".join(lines)
+
+
+async def ask(state: State) -> dict[str, Any]:
+    question = _question(state)
+    if not question:
+        return {"messages": [AIMessage("Ask me a question about the data.")]}
+    history = list(state.get("history") or [])
+    try:
+        answer = await get_data_space_client().ask(_space_id(), question, history=history)
+    except SignInRequired as exc:
+        request_sign_in(exc)  # the sign-in card, on every surface
+        return {"messages": [AIMessage(SIGN_IN_REPLY)]}
+    except BuildingBlockForbiddenError:
+        # A refusal that no sign-in can change. Answer it: a failed run reads as "the agent is down".
+        return {"messages": [AIMessage(NO_ACCESS_REPLY)]}
+    if not answer.ok:
+        error = answer.error or {}
+        reason = error.get("message") or error.get("code") or "unknown reason"
+        return {"messages": [AIMessage(f"The data space could not answer this question: {reason}")]}
+    history.append({"question": question, "sql": answer.sql})
+    return {"messages": [AIMessage(format_answer(answer))], "history": history}
+
+
+def make_graph():
+    g = StateGraph(State)
+    g.add_node("ask", ask)
+    g.set_entry_point("ask")
+    g.set_finish_point("ask")
+    return g

keystone_cli-0.4.0/src/keystone_cli/templates/data-space/pyproject.toml.tmpl

@@ -0,0 +1,24 @@
+[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 = [
+    # >=0.13.15: DataSpaceClient, SignInRequired and ui.request_sign_in landed there.
+    "keystone-agent-sdk>=0.13.15",
+    "langgraph>=1,<2",
+    "langchain-core>=1,<2",
+]
+
+# Unit tests: `keystone agent test` runs tests/ in the CLI's environment. `uv run pytest` installs
+# this group and runs them in the project's own environment (for an agent with its own libraries).
+[dependency-groups]
+dev = ["pytest>=8,<9", "anyio>=4", "keystone-agent-sdk>=0.13.15"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = "-ra --strict-markers"