From bb3476a4e6370658f6689c9bc6f5f81730bdaf78 Mon Sep 17 00:00:00 2001
From: Adrian Kahali <adrian.kahali@hotmail.com>
Date: Tue, 27 Jan 2026 17:06:35 -0500
Subject: [PATCH] feat(adk): doc context and adk apis

---
 adk/cli-reference.mdx |  68 +++++++-
 adk/runtime.mdx       | 390 ++++++++++++++++++++++++++++++++++++++++++
 docs.json             |   1 +
 3 files changed, 457 insertions(+), 2 deletions(-)
 create mode 100644 adk/runtime.mdx

diff --git a/adk/cli-reference.mdx b/adk/cli-reference.mdx
index b2e0abbe..c78e08a2 100644
--- a/adk/cli-reference.mdx
+++ b/adk/cli-reference.mdx
@@ -127,7 +127,7 @@ adk add webchat --alias custom-webchat
 
 ### `adk chat`
 
-Chat with your deployed bot directly from the CLI.
+Chat with your agent in development mode directly from the CLI.
 
 **Usage:**
 ```bash
@@ -140,6 +140,62 @@ Run `adk dev` first to create a development bot if you don't have a `devId` in y
 
 ---
 
+### `adk run`
+
+Run a TypeScript script with the ADK runtime fully initialized. This allows you to execute scripts that use your agent's primitives, integrations, and runtime utilities like `client`, `context`, and `adk`.
+
+**Usage:**
+```bash
+adk run <script> [args...]
+adk run scripts/migrate-data.ts
+adk run scripts/seed-tables.ts --prod
+adk run scripts/analyze.ts arg1 arg2
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `script` | Path to the TypeScript script file to run |
+| `args` | Optional arguments to pass to the script |
+
+**Flags:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-f, --force` | Force regeneration of the bot project | `false` |
+| `--prod` | Use production bot instead of dev bot | `false` |
+
+**Script exports:**
+
+Your script can export a function that will be called automatically:
+
+```typescript
+// Option 1: Default export
+export default async function(arg1: string, arg2: string) {
+  // Script logic
+}
+
+// Option 2: Named 'run' export
+export async function run(arg1: string, arg2: string) {
+  // Script logic
+}
+
+// Option 3: Named 'main' export
+export async function main(arg1: string, arg2: string) {
+  // Script logic
+}
+
+// Option 4: Top-level code (runs on import)
+console.log("Script executed!")
+```
+
+<Tip>
+Use `adk run` to execute migrations, seed data, run maintenance tasks, or any script that needs access to your agent's runtime context.
+</Tip>
+
+---
+
 ### `adk mcp`
 
 Start an MCP (Model Context Protocol) server for AI assistant integration. This allows AI coding assistants like Claude Code and Cursor to interact with your ADK agent.
@@ -373,13 +429,21 @@ adk link --workspace <workspaceId> --bot <botId> --dev <devBotId>
 
 ### `adk self-upgrade`
 
-Upgrade ADK CLI to the latest version.
+Upgrade ADK CLI to the latest version or a specific version/tag.
 
 **Usage:**
 ```bash
 adk self-upgrade
+adk self-upgrade beta
+adk self-upgrade 1.13.0
 ```
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `tag-or-version` | Optional. Tag (`beta`, `next`) or specific version (`1.13.0`) to install |
+
 **Aliases:** `self-update`
 
 ---
diff --git a/adk/runtime.mdx b/adk/runtime.mdx
new file mode 100644
index 00000000..ae2a65f0
--- /dev/null
+++ b/adk/runtime.mdx
@@ -0,0 +1,390 @@
+---
+title: Runtime utilities
+---
+
+The ADK provides runtime utilities for accessing the execution context, Botpress client, and project information from anywhere in your agent's code.
+
+## Client
+
+The `client` export provides direct access to the Botpress API client. Unlike the `client` passed to handlers, this export works from any file in your agent—including utility functions, shared modules, and scripts run with `adk run`.
+
+<CodeGroup>
+```typescript List conversations
+import { client } from "@botpress/runtime";
+
+const { conversations } = await client.listConversations({});
+console.log(conversations);
+```
+
+```typescript Get a user
+import { client } from "@botpress/runtime";
+
+const { user } = await client.getUser({ id: userId });
+console.log(user);
+```
+
+```typescript Create a message
+import { client } from "@botpress/runtime";
+
+const message = await client.createMessage({
+  conversationId,
+  userId,
+  type: "text",
+  payload: { text: "Hello from a utility function" },
+});
+console.log(message);
+```
+</CodeGroup>
+
+The client automatically uses the correct authentication:
+- **During request handling**: Uses the bot-specific client from the current execution context
+- **In scripts (`adk run`)**: Creates a client using `ADK_TOKEN` and `ADK_BOT_ID` environment variables
+
+<Tip>
+Use this export when you need to call the Botpress API from utility functions or shared modules that don't receive the client as a parameter.
+</Tip>
+
+## Context
+
+The `context` API provides low-level access to the current execution context. It's built on Node.js `AsyncLocalStorage` and contains all runtime information about the current request.
+
+### Getting context about the current execution
+
+You can use `context.get()` to access specific values from the current execution:
+
+<CodeGroup>
+```typescript Get bot ID
+import { context } from "@botpress/runtime";
+
+const botId = context.get("botId");
+console.log(botId);
+```
+
+```typescript Get conversation
+import { context } from "@botpress/runtime";
+
+const conversation = context.get("conversation", { optional: true });
+console.log(conversation);
+```
+
+```typescript Get user
+import { context } from "@botpress/runtime";
+
+const user = context.get("user", { optional: true });
+console.log(user);
+```
+
+```typescript Get runtime info
+import { context } from "@botpress/runtime";
+
+const runtime = context.get("runtime");
+const remainingMs = runtime.getRemainingExecutionTimeInMs();
+console.log(remainingMs);
+```
+</CodeGroup>
+
+The `optional` flag prevents errors when a value might not exist in the current context. Without it, accessing a missing key throws an error.
+
+<Note>
+  Check the [reference](#reference) for a full list of available context values.
+</Note>
+
+### Setting a default context
+
+When running scripts with `adk run`, you may need to set up a default context for code that expects to run within a request:
+
+```typescript
+import { context } from "@botpress/runtime";
+
+context.setDefaultContext({
+  botId: "my-bot-id",
+  // Other context values as needed
+});
+
+// Now context.get() calls will use this default
+const botId = context.get("botId"); // "my-bot-id"
+
+// Clean up when done
+context.clearDefaultContext();
+```
+
+<Note>
+The `adk run` command automatically sets up the default context with authentication. You typically only need `setDefaultContext` for testing or custom script environments.
+</Note>
+
+### Checking execution time
+
+Long-running operations should check remaining execution time to avoid timeouts:
+
+```typescript
+import { context } from "@botpress/runtime";
+
+async function processLargeDataset(items: Item[]) {
+  const SAFETY_MARGIN = 5000;
+
+  for (const item of items) {
+    const remaining = context.get("runtime").getRemainingExecutionTimeInMs();
+
+    if (remaining < SAFETY_MARGIN) {
+      await saveProgress(items.indexOf(item));
+      return { completed: false, processedCount: items.indexOf(item) };
+    }
+
+    await processItem(item);
+  }
+
+  return { completed: true, processedCount: items.length };
+}
+```
+
+### Reference
+
+<ResponseField name="get" type="(key: string, opts?: { optional?: boolean }) => any" required>
+  Get a specific value from the current execution context. Throws an error if the key doesn't exist unless `optional: true` is passed.
+  <Expandable title="Available context values">
+    <ResponseField name="executionId" type="string" required>
+      Unique identifier for the current execution.
+    </ResponseField>
+    <ResponseField name="botId" type="string" required>
+      The bot's unique identifier.
+    </ResponseField>
+    <ResponseField name="bot" type="object" required>
+      Bot metadata including `id`, `tags`, `userId`, and `configuration`.
+    </ResponseField>
+    <ResponseField name="client" type="Client" required>
+      The authenticated Botpress client for this execution.
+    </ResponseField>
+    <ResponseField name="cognitive" type="Cognitive" required>
+      The Cognitive AI client for LLM operations.
+    </ResponseField>
+    <ResponseField name="logger" type="BotLogger" required>
+      Logger instance for the current execution.
+    </ResponseField>
+    <ResponseField name="configuration" type="object" required>
+      The bot's configuration values (from `agent.config.ts`).
+    </ResponseField>
+    <ResponseField name="conversation" type="Conversation">
+      The current conversation object. Only available in conversation and message contexts.
+    </ResponseField>
+    <ResponseField name="user" type="User">
+      The current user object. Only available when a user is associated with the request.
+    </ResponseField>
+    <ResponseField name="event" type="Event">
+      The current event object. Available in event and trigger handlers.
+    </ResponseField>
+    <ResponseField name="message" type="Message">
+      The current message object. Only available in message handlers.
+    </ResponseField>
+    <ResponseField name="workflow" type="Workflow">
+      The current workflow object. Only available in workflow handlers.
+    </ResponseField>
+    <ResponseField name="runtime" type="object" required>
+      Runtime environment information.
+      <Expandable title="Runtime properties">
+        <ResponseField name="sandboxName" type="string" required>
+          Name of the execution sandbox.
+        </ResponseField>
+        <ResponseField name="memoryInMb" type="number" required>
+          Memory limit in megabytes.
+        </ResponseField>
+        <ResponseField name="getRemainingExecutionTimeInMs" type="() => number" required>
+          Function that returns the remaining execution time in milliseconds.
+        </ResponseField>
+      </Expandable>
+    </ResponseField>
+    <ResponseField name="citations" type="CitationsManager" required>
+      Manager for tracking citations in AI responses.
+    </ResponseField>
+    <ResponseField name="states" type="TrackedState[]" required>
+      Array of tracked state objects for the current execution.
+    </ResponseField>
+    <ResponseField name="tags" type="TrackedTags[]" required>
+      Array of tracked tag objects for the current execution.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+<ResponseField name="getAll" type="() => BotContext" required>
+  Get the entire context object for the current execution.
+</ResponseField>
+<ResponseField name="set" type="(key: string, value: any) => void" required>
+  Set a value in the current execution context. Can only be called within an active context.
+</ResponseField>
+<ResponseField name="setDefaultContext" type="(data: Partial&lt;BotContext&gt;) => void" required>
+  Set a default context used as a fallback when no execution context is active. Useful for testing and script execution.
+</ResponseField>
+<ResponseField name="clearDefaultContext" type="() => void" required>
+  Clear the default context.
+</ResponseField>
+
+## ADK object
+
+The `adk` export provides access to project configuration and utilities for autonomous execution outside of conversations.
+
+### Getting project information
+
+You can use the `adk` object to read your agent's primitives, configuration and more:
+
+<CodeGroup>
+```typescript Get configuration
+import { adk } from "@botpress/runtime";
+
+const config = adk.project.config;
+console.log(config.name, config.defaultModels);
+```
+
+```typescript List primitives
+import { adk } from "@botpress/runtime";
+
+const workflows = adk.project.workflows;
+const tables = adk.project.tables;
+const conversations = adk.project.conversations;
+console.log(workflows, tables, conversations);
+```
+
+```typescript Get integration
+import { adk } from "@botpress/runtime";
+
+const webchat = adk.project.integrations.get("webchat");
+console.log(webchat);
+```
+</CodeGroup>
+
+### Running an autonomous agent
+
+You can run an autonomous agent outside of a [Conversation](/adk/concepts/conversations) context. This is useful for scripts, migrations, or background tasks:
+
+```typescript
+import { adk, Autonomous, z } from "@botpress/runtime";
+
+const analyzeData = new Autonomous.Tool({
+  name: "analyzeData",
+  description: "Analyze dataset and return insights",
+  input: z.object({ datasetId: z.string() }),
+  output: z.object({ insights: z.array(z.string()) }),
+  handler: async ({ datasetId }) => {
+    // Analysis logic
+    return { insights: ["Finding 1", "Finding 2"] };
+  },
+});
+
+const result = await adk.execute({
+  instructions: "Analyze the sales data and summarize key trends",
+  tools: [analyzeData],
+  iterations: 5,
+});
+```
+
+### Using Zai
+
+The `adk` object gives you access to the [Zai utility library](/adk/zai/overview). You can use Zai to perform type-safe AI operations on arbitrary data:
+
+```typescript
+import { adk, z } from "@botpress/runtime";
+
+const summary = await adk.zai.generate({
+  instructions: "Summarize this text in 2 sentences",
+  input: longText,
+  output: z.object({
+    summary: z.string(),
+    wordCount: z.number(),
+  }),
+});
+```
+
+<Note>
+  For a full list of Zai's methods, check out the [Zai reference documentation](/adk/zai/reference).
+</Note>
+
+### Checking the execution environment
+
+You can check the current execution environment:
+
+<CodeGroup>
+```typescript Check development
+import { adk } from "@botpress/runtime";
+
+if (adk.environment.isDevelopment()) {
+  console.log("Running in development mode");
+}
+```
+
+```typescript Check production
+import { adk } from "@botpress/runtime";
+
+if (adk.environment.isProduction()) {
+  console.log("Running in production mode");
+}
+```
+</CodeGroup>
+
+This is useful if you need to run code only in specific environments—for example, enabling verbose logging or loading mock data during local development, while skipping it in production.
+
+### Reference
+
+<ResponseField name="project" type="Project" required>
+  Project primitives and configuration.
+  <Expandable title="Project properties">
+    <ResponseField name="config" type="AgentConfig" required>
+      Agent configuration from `agent.config.ts`.
+    </ResponseField>
+    <ResponseField name="integrations" type="Integration[]" required>
+      Installed integrations with typed actions. Use `.get(name)` to retrieve a specific integration.
+    </ResponseField>
+    <ResponseField name="actions" type="Action[]" required>
+      Registered action primitives.
+    </ResponseField>
+    <ResponseField name="knowledge" type="Knowledge[]" required>
+      Registered knowledge base primitives.
+    </ResponseField>
+    <ResponseField name="tables" type="Table[]" required>
+      Registered table primitives.
+    </ResponseField>
+    <ResponseField name="workflows" type="Workflow[]" required>
+      Registered workflow primitives.
+    </ResponseField>
+    <ResponseField name="conversations" type="Conversation[]" required>
+      Registered conversation primitives.
+    </ResponseField>
+    <ResponseField name="triggers" type="Trigger[]" required>
+      Registered trigger primitives.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+<ResponseField name="zai" type="Zai" required>
+  Zai LLM utility toolkit instance configured with the project's default model.
+</ResponseField>
+<ResponseField name="environment" type="Environment" required>
+  Environment detection utilities including `isDevelopment()` and `isProduction()` methods.
+</ResponseField>
+<ResponseField name="execute" type="(props: Autonomous.Props) => Promise&lt;ExecuteResult&gt;" required>
+  Execute an autonomous LLM agent outside of a conversation context.
+  <Expandable title="Execute parameters">
+    <ResponseField name="instructions" type="string" required>
+      Instructions for the autonomous agent.
+    </ResponseField>
+    <ResponseField name="tools" type="Tool[]">
+      Array of tools the agent can use.
+    </ResponseField>
+    <ResponseField name="objects" type="object[]">
+      Array of objects the agent can interact with.
+    </ResponseField>
+    <ResponseField name="exits" type="Record&lt;string, object&gt;">
+      Exit handlers for the agent.
+    </ResponseField>
+    <ResponseField name="signal" type="AbortSignal">
+      Abort signal to cancel execution.
+    </ResponseField>
+    <ResponseField name="temperature" type="number | (() => number)">
+      Temperature for the AI model. Defaults to 0.7.
+    </ResponseField>
+    <ResponseField name="model" type="string | string[]">
+      Model name(s) to use. Defaults to the project's `defaultModels.autonomous` setting.
+    </ResponseField>
+    <ResponseField name="iterations" type="number">
+      Maximum number of iterations. Defaults to 10.
+    </ResponseField>
+    <ResponseField name="hooks" type="object">
+      Execution hooks including `onTrace`, `onIterationEnd`, `onBeforeTool`, `onAfterTool`, `onBeforeExecution`, and `onExit`.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
diff --git a/docs.json b/docs.json
index a5a42dce..db81f4bb 100644
--- a/docs.json
+++ b/docs.json
@@ -108,6 +108,7 @@
                 ]
               },
               "/adk/managing-integrations",
+              "/adk/runtime",
               {
                 "group": "Zai",
                 "pages": ["/adk/zai/overview", "/adk/zai/reference"]