Skip to main content
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. 
import { client } from "@botpress/runtime";

const { conversations } = await client.listConversations({});
console.log(conversations);
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
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.

​
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: 
import { context } from "@botpress/runtime";

const botId = context.get("botId");
console.log(botId);
The optional flag prevents errors when a value might not exist in the current context. Without it, accessing a missing key throws an error.
Check the reference for a full list of available context values.

​
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: 
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();
The adk run command automatically sets up the default context with authentication. You typically only need setDefaultContext for testing or custom script environments.

​
Checking execution time

Long-running operations should check remaining execution time to avoid timeouts: 
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

​
get
(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.
​
getAll
() => BotContext
required
Get the entire context object for the current execution.
​
set
(key: string, value: any) => void
required
Set a value in the current execution context. Can only be called within an active context.
​
setDefaultContext
(data: Partial<BotContext>) => void
required
Set a default context used as a fallback when no execution context is active. Useful for testing and script execution.
​
clearDefaultContext
() => void
required
Clear the default context.

​
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: 
import { adk } from "@botpress/runtime";

const config = adk.project.config;
console.log(config.name, config.defaultModels);

​
Running an autonomous agent

You can run an autonomous agent outside of a Conversation context. This is useful for scripts, migrations, or background tasks: 
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. You can use Zai to perform type-safe AI operations on arbitrary data: 
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(),
  }),
});
For a full list of Zai’s methods, check out the Zai reference documentation.

​
Checking the execution environment

You can check the current execution environment: 
import { adk } from "@botpress/runtime";

if (adk.environment.isDevelopment()) {
  console.log("Running in development mode");
}
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

​
project
Project
required
Project primitives and configuration.
​
zai
Zai
required
Zai LLM utility toolkit instance configured with the project’s default model.
​
environment
Environment
required
Environment detection utilities including isDevelopment() and isProduction() methods.
​
execute
(props: Autonomous.Props) => Promise<ExecuteResult>
required
Execute an autonomous LLM agent outside of a conversation context.
Last modified on January 27, 2026