From b7fcda101a1fd7ef6aeb81cfd61c75f6b859a3fc Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Mon, 6 Apr 2026 10:40:16 -0400 Subject: [PATCH 01/28] docs(adk): create State and Configuration concept pages (ADK-304, ADK-303) --- adk/concepts/configuration.mdx | 211 +++++++++++++++++++++++++++++++++ adk/concepts/state.mdx | 200 +++++++++++++++++++++++++++++++ docs.json | 4 +- 3 files changed, 414 insertions(+), 1 deletion(-) create mode 100644 adk/concepts/configuration.mdx create mode 100644 adk/concepts/state.mdx diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx new file mode 100644 index 00000000..9a51b0e4 --- /dev/null +++ b/adk/concepts/configuration.mdx @@ -0,0 +1,211 @@ +--- +title: Configuration +--- + +Configuration defines your agent's identity, models, state schemas, dependencies, and runtime settings. Everything is centralized in `agent.config.ts`. + +## `agent.config.ts` + +The main configuration file uses `defineConfig` from `@botpress/runtime`: + +```typescript +import { z, defineConfig } from "@botpress/runtime"; + +export default defineConfig({ + name: "my-agent", + description: "An AI agent built with Botpress ADK", + + defaultModels: { + autonomous: "openai:gpt-4.1-mini-2025-04-14", + zai: "openai:gpt-4.1-2025-04-14", + }, + + bot: { + state: z.object({}), + tags: {}, + }, + + user: { + state: z.object({}), + tags: {}, + }, + + conversation: { + tags: {}, + }, + + message: { + tags: {}, + }, + + workflow: { + tags: {}, + }, + + configuration: { + schema: z.object({ + apiKey: z.string(), + maxRetries: z.number().default(3), + }), + }, + + dependencies: { + integrations: { + chat: { version: "chat@0.7.7", enabled: true }, + webchat: { version: "webchat@0.3.0", enabled: true }, + }, + }, +}); +``` + +## Config options + + + + Agent name. Used to identify your agent in the Botpress dashboard. + + + Optional description of your agent. + + + Default LLM models for your agent. + + + Model used for `execute()` calls in conversations and workflows. + + + Model used for Zai operations (`zai.extract()`, `zai.check()`, etc.). + + + + + Bot-level state schema and tags. See [State](/adk/concepts/state). + + + User-level state schema and tags. See [State](/adk/concepts/state). + + + Conversation-level tags. + + + Message-level tags. + + + Workflow-level tags. + + + Runtime configuration schema. Values are set via `adk config` and accessed at runtime via the `configuration` import. + + + A Zod object schema defining the configuration fields. Must be `z.object()`. + + + + + Integration and interface dependencies. See [Managing Integrations](/adk/managing-integrations). + + + Custom event definitions. Each key is an event name, with an optional schema and description. + + + +## Accessing configuration at runtime + +Import `configuration` from `@botpress/runtime` to access your agent's configuration values: + +```typescript +import { configuration } from "@botpress/runtime"; + +const apiKey = configuration.apiKey; +const maxRetries = configuration.maxRetries; +``` + +Configuration values are defined by the `configuration.schema` in `agent.config.ts` and set via the `adk config` command or the Botpress dashboard. + + + Configuration is read-only at runtime. Attempting to set a value will throw an error. + + +## Managing configuration + +### Interactive configuration + +Run `adk config` to interactively set all configuration values: + +```bash +adk config +``` + +This validates your values against the schema and prompts for any missing or invalid fields. + +### Get and set values + +Set individual configuration values non-interactively: + +```bash +adk config:set apiKey sk-my-api-key +adk config:get apiKey +``` + +### Production configuration + +Use the `--prod` flag to manage production configuration separately from development: + +```bash +adk config --prod +adk config:set apiKey sk-prod-key --prod +adk config:get apiKey --prod +``` + +## Default models + +The `defaultModels` field sets which LLM models your agent uses: + +```typescript +defaultModels: { + autonomous: "openai:gpt-4.1-mini-2025-04-14", + zai: "openai:gpt-4.1-2025-04-14", +}, +``` + +- **`autonomous`** — used by `execute()` in conversations and workflows +- **`zai`** — used by Zai operations like `zai.extract()`, `zai.check()`, `zai.text()` + +You can override the model per-call using the `model` prop on `execute()`. + +## Custom events + +Define custom events that your agent can emit and listen to: + +```typescript highlight={3-8} +export default defineConfig({ + name: "my-agent", + events: { + orderPlaced: { + description: "Fired when an order is placed", + schema: z.object({ + orderId: z.string(), + total: z.number(), + }), + }, + }, +}); +``` + +Custom events can be subscribed to in [Triggers](/adk/concepts/triggers) and [Conversations](/adk/concepts/conversations) (via the `events` prop). + +## Dependencies + +The `dependencies` field declares which integrations your agent uses: + +```typescript +dependencies: { + integrations: { + chat: { version: "chat@0.7.7", enabled: true }, + webchat: { version: "webchat@0.3.0", enabled: true }, + slack: { version: "slack@1.0.0", enabled: true }, + }, +}, +``` + +See [Managing Integrations](/adk/managing-integrations) for details on adding, removing, and configuring integrations. diff --git a/adk/concepts/state.mdx b/adk/concepts/state.mdx new file mode 100644 index 00000000..0edc7850 --- /dev/null +++ b/adk/concepts/state.mdx @@ -0,0 +1,200 @@ +--- +title: State +--- + +State lets your agent persist data across conversations, users, and the entire bot. The ADK provides three state scopes, each with different lifetimes and access patterns. + +## State scopes + +| Scope | Lifetime | Access | Defined in | +|-------|----------|--------|------------| +| Bot | Global, shared across all users and conversations | `bot.state` | `agent.config.ts` | +| User | Per-user, persists across all of a user's conversations | `user.state` | `agent.config.ts` | +| Conversation | Per-conversation, scoped to a single conversation | Handler's `state` parameter | Conversation definition | + +## Defining state schemas + +### Bot and user state + +Define bot and user state schemas in `agent.config.ts`: + +```typescript highlight={8-11, 14-18} +import { z, defineConfig } from "@botpress/runtime"; + +export default defineConfig({ + name: "my-agent", + + bot: { + state: z.object({ + version: z.number(), + ticketCounter: z.number(), + }).default({ version: 0, ticketCounter: 0 }), + }, + + user: { + state: z.object({ + name: z.string().optional(), + department: z.string().optional(), + visitCount: z.number().default(0), + }), + }, +}); +``` + + + Use `.default()` on your state schema to set initial values. Without defaults, state fields start as `undefined`. + + +### Conversation state + +Conversation state is defined on each Conversation definition using the `state` prop: + +```typescript highlight={5-8} +import { Conversation, z } from "@botpress/runtime"; + +export default new Conversation({ + channel: "*", + state: z.object({ + topic: z.string().optional(), + messageCount: z.number().default(0), + }), + handler: async ({ execute, state }) => { + state.messageCount += 1; + + await execute({ + instructions: `You are a helpful assistant. Messages so far: ${state.messageCount}`, + }); + }, +}); +``` + +## Reading and writing state + +### Bot state + +Import `bot` from `@botpress/runtime` to access bot-level state from anywhere in your agent: + +```typescript +import { bot } from "@botpress/runtime"; + +// Read +const counter = bot.state.ticketCounter; + +// Write +bot.state.ticketCounter = counter + 1; +``` + +### User state + +Import `user` from `@botpress/runtime` to access per-user state: + +```typescript +import { user } from "@botpress/runtime"; + +// Read +const name = user.state.name; + +// Write +user.state.visitCount = (user.state.visitCount || 0) + 1; +``` + +### Conversation state + +Conversation state is accessed via the `state` parameter in the handler: + +```typescript +export default new Conversation({ + channel: "*", + state: z.object({ + phase: z.string().default("greeting"), + }), + handler: async ({ state, execute }) => { + if (state.phase === "greeting") { + state.phase = "main"; + } + + await execute({ + instructions: `Current phase: ${state.phase}`, + }); + }, +}); +``` + + + State changes are automatically tracked and persisted. You don't need to call a save method — just mutate the state object directly. + + +## Tags + +Tags are string key-value pairs you can attach to bots, users, conversations, messages, and workflows. They're useful for categorization, filtering, and querying. + +### Defining tags + +Define tag schemas in `agent.config.ts`: + +```typescript highlight={5-11} +export default defineConfig({ + name: "my-agent", + + bot: { + tags: { + environment: { title: "Environment", description: "Current deployment environment" }, + }, + }, + + user: { + tags: { + role: { title: "Role", description: "User's role in the organization" }, + }, + }, + + conversation: { + tags: { + priority: { title: "Priority", description: "Conversation priority level" }, + }, + }, +}); +``` + +### Reading and writing tags + +```typescript +import { bot, user } from "@botpress/runtime"; + +// Bot tags +bot.tags.environment = "production"; +const env = bot.tags.environment; + +// User tags +user.tags.role = "admin"; +``` + +Conversation tags are accessed via the `conversation` instance in handlers: + +```typescript +export default new Conversation({ + channel: "*", + handler: async ({ conversation, execute }) => { + // Read + const priority = conversation.tags.priority; + + // Write + conversation.tags.priority = "high"; + }, +}); +``` + + + System tags (set by integrations, containing `:` in the key) are read-only. You can read them but any writes are silently ignored. + + +## Bot and user identity + +The `bot` and `user` objects also expose an `id` property: + +```typescript +import { bot, user } from "@botpress/runtime"; + +const botId = bot.id; +const userId = user.id; +``` diff --git a/docs.json b/docs.json index 52a3a09a..42a1392a 100644 --- a/docs.json +++ b/docs.json @@ -104,7 +104,9 @@ "/adk/concepts/tables", "/adk/concepts/triggers", "/adk/concepts/knowledge", - "/adk/concepts/tools" + "/adk/concepts/tools", + "/adk/concepts/state", + "/adk/concepts/configuration" ] }, "/adk/managing-integrations", From 2caa13c377be8a00e353446402b182a27152a0dc Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Mon, 6 Apr 2026 10:55:27 -0400 Subject: [PATCH 02/28] docs(adk): fix default models to match adk init output --- adk/concepts/configuration.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx index 9a51b0e4..adeb3ad6 100644 --- a/adk/concepts/configuration.mdx +++ b/adk/concepts/configuration.mdx @@ -16,8 +16,8 @@ export default defineConfig({ description: "An AI agent built with Botpress ADK", defaultModels: { - autonomous: "openai:gpt-4.1-mini-2025-04-14", - zai: "openai:gpt-4.1-2025-04-14", + autonomous: "cerebras:gpt-oss-120b", + zai: "cerebras:gpt-oss-120b", }, bot: { @@ -163,8 +163,8 @@ The `defaultModels` field sets which LLM models your agent uses: ```typescript defaultModels: { - autonomous: "openai:gpt-4.1-mini-2025-04-14", - zai: "openai:gpt-4.1-2025-04-14", + autonomous: "cerebras:gpt-oss-120b", + zai: "cerebras:gpt-oss-120b", }, ``` From ae3222a892a2cebbb2d86b404edb9aea1706a9b3 Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Mon, 6 Apr 2026 11:03:55 -0400 Subject: [PATCH 03/28] docs(adk): add real CLI output, clarify adk config vs integration config --- adk/concepts/configuration.mdx | 41 +++++++++++++++++++++++++++++----- 1 file changed, 35 insertions(+), 6 deletions(-) diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx index adeb3ad6..610df9f3 100644 --- a/adk/concepts/configuration.mdx +++ b/adk/concepts/configuration.mdx @@ -130,21 +130,46 @@ Configuration values are defined by the `configuration.schema` in `agent.config. ### Interactive configuration -Run `adk config` to interactively set all configuration values: +Run `adk config` to validate and interactively set all configuration values: ```bash adk config ``` +```txt +📝 Configuration (development) + +✓ Configuration validated successfully +``` + This validates your values against the schema and prompts for any missing or invalid fields. + + `adk config` requires a `configuration.schema` in your `agent.config.ts`. Without one, you'll see "No configuration schema defined." + + ### Get and set values -Set individual configuration values non-interactively: +Set and retrieve individual configuration values: ```bash -adk config:set apiKey sk-my-api-key -adk config:get apiKey +adk config:set supportEmail "help@mycompany.com" +``` + +```txt +✓ Configuration updated (development) + supportEmail = help@mycompany.com +``` + +```bash +adk config:get supportEmail +``` + +```txt +📝 Configuration value (development) + + Key: supportEmail + Value: help@mycompany.com ``` ### Production configuration @@ -153,10 +178,14 @@ Use the `--prod` flag to manage production configuration separately from develop ```bash adk config --prod -adk config:set apiKey sk-prod-key --prod -adk config:get apiKey --prod +adk config:set supportEmail "help@mycompany.com" --prod +adk config:get supportEmail --prod ``` + + Agent configuration (`adk config`) is separate from integration configuration. Integration settings like API keys are configured in `agent.config.ts` under `dependencies` or via the Control Panel during `adk dev`. See [Managing Integrations](/adk/managing-integrations) for details. + + ## Default models The `defaultModels` field sets which LLM models your agent uses: From 89ebaccdc0081664871ae7c68a2a9acd68a254c8 Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Mon, 6 Apr 2026 11:15:02 -0400 Subject: [PATCH 04/28] docs(adk): add env variables section, evals config option (ADK-303) --- adk/concepts/configuration.mdx | 35 ++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx index 610df9f3..b2fe7fe5 100644 --- a/adk/concepts/configuration.mdx +++ b/adk/concepts/configuration.mdx @@ -107,6 +107,20 @@ export default defineConfig({ Custom event definitions. Each key is an event name, with an optional schema and description. + + Optional evaluation settings. + + + Timeout in seconds for idle eval conversations. + + + Pass threshold for LLM judge assertions (1–5). + + + Model to use for LLM judge assertions (e.g., `"openai:gpt-4o"`). + + + ## Accessing configuration at runtime @@ -186,6 +200,27 @@ adk config:get supportEmail --prod Agent configuration (`adk config`) is separate from integration configuration. Integration settings like API keys are configured in `agent.config.ts` under `dependencies` or via the Control Panel during `adk dev`. See [Managing Integrations](/adk/managing-integrations) for details. +## Environment variables + +You can use `process.env` directly in `agent.config.ts` and throughout your agent code: + +```typescript +export default defineConfig({ + name: "my-agent", + configuration: { + schema: z.object({ + apiKey: z.string().default(process.env.MY_API_KEY ?? ""), + }), + }, +}); +``` + +The ADK also injects its own environment variables during `adk dev` and `adk run` (such as `ADK_CONFIGURATION` and `ADK_BOT_ID`), but these are managed internally. + + + There is no dedicated secrets API in the ADK. For integration secrets (like API keys for Slack or BambooHR), set them via the Botpress dashboard — they're stored server-side and preserved during deployments. + + ## Default models The `defaultModels` field sets which LLM models your agent uses: From ae07f2ad35aa0654d0ded823b95f818e6a991512 Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Mon, 6 Apr 2026 11:20:13 -0400 Subject: [PATCH 05/28] docs(adk): minor wording fixes in state and configuration pages --- adk/concepts/configuration.mdx | 8 ++++---- adk/concepts/state.mdx | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx index b2fe7fe5..488ec4af 100644 --- a/adk/concepts/configuration.mdx +++ b/adk/concepts/configuration.mdx @@ -114,7 +114,7 @@ export default defineConfig({ Timeout in seconds for idle eval conversations. - Pass threshold for LLM judge assertions (1–5). + Pass threshold for LLM judge assertions (1-5). Model to use for LLM judge assertions (e.g., `"openai:gpt-4o"`). @@ -218,7 +218,7 @@ export default defineConfig({ The ADK also injects its own environment variables during `adk dev` and `adk run` (such as `ADK_CONFIGURATION` and `ADK_BOT_ID`), but these are managed internally. - There is no dedicated secrets API in the ADK. For integration secrets (like API keys for Slack or BambooHR), set them via the Botpress dashboard — they're stored server-side and preserved during deployments. + There is no dedicated secrets API in the ADK. For integration secrets (like API keys for Slack or BambooHR), set them via the Botpress dashboard. They're stored server-side and preserved during deployments. ## Default models @@ -232,8 +232,8 @@ defaultModels: { }, ``` -- **`autonomous`** — used by `execute()` in conversations and workflows -- **`zai`** — used by Zai operations like `zai.extract()`, `zai.check()`, `zai.text()` +- **`autonomous`**: used by `execute()` in conversations and workflows +- **`zai`**: used by Zai operations like `zai.extract()`, `zai.check()`, `zai.text()` You can override the model per-call using the `model` prop on `execute()`. diff --git a/adk/concepts/state.mdx b/adk/concepts/state.mdx index 0edc7850..b328d7a4 100644 --- a/adk/concepts/state.mdx +++ b/adk/concepts/state.mdx @@ -121,7 +121,7 @@ export default new Conversation({ ``` - State changes are automatically tracked and persisted. You don't need to call a save method — just mutate the state object directly. + State changes are automatically tracked and persisted. You don't need to call a save method: just mutate the state object directly. ## Tags From f076eb218d9acdc2077242904697ef55cf2352fd Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Mon, 6 Apr 2026 11:25:03 -0400 Subject: [PATCH 06/28] docs(adk): improve env variables section with practical API key example --- adk/concepts/configuration.mdx | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx index 488ec4af..a4970037 100644 --- a/adk/concepts/configuration.mdx +++ b/adk/concepts/configuration.mdx @@ -202,23 +202,29 @@ adk config:get supportEmail --prod ## Environment variables -You can use `process.env` directly in `agent.config.ts` and throughout your agent code: +You can use `process.env` directly in `agent.config.ts` and throughout your agent code. This is useful for keeping sensitive values like API keys out of your source code: ```typescript -export default defineConfig({ - name: "my-agent", - configuration: { - schema: z.object({ - apiKey: z.string().default(process.env.MY_API_KEY ?? ""), - }), - }, -}); +configuration: { + schema: z.object({ + apiKey: z.string().default(process.env.MY_API_KEY ?? ""), + webhookUrl: z.string().default(process.env.WEBHOOK_URL ?? ""), + }), +}, ``` -The ADK also injects its own environment variables during `adk dev` and `adk run` (such as `ADK_CONFIGURATION` and `ADK_BOT_ID`), but these are managed internally. +Then access them at runtime via the typed `configuration` import: + +```typescript +import { configuration } from "@botpress/runtime"; + +const response = await fetch("https://api.example.com/data", { + headers: { Authorization: `Bearer ${configuration.apiKey}` }, +}); +``` - There is no dedicated secrets API in the ADK. For integration secrets (like API keys for Slack or BambooHR), set them via the Botpress dashboard. They're stored server-side and preserved during deployments. + There is no dedicated secrets API in the ADK. For integration-specific credentials (like OAuth tokens), configure them in `agent.config.ts` under `dependencies` or via the Botpress dashboard. See [Managing Integrations](/adk/managing-integrations) for details. ## Default models From 279df5810e7447e6dcd5a1a69977df2541baf04a Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Mon, 6 Apr 2026 11:27:19 -0400 Subject: [PATCH 07/28] docs(adk): add state references section (ADK-304) --- adk/concepts/state.mdx | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/adk/concepts/state.mdx b/adk/concepts/state.mdx index b328d7a4..5aa3c124 100644 --- a/adk/concepts/state.mdx +++ b/adk/concepts/state.mdx @@ -188,6 +188,27 @@ export default new Conversation({ System tags (set by integrations, containing `:` in the key) are read-only. You can read them but any writes are silently ignored. +## State references + +You can store references to workflow instances in state. They are automatically serialized when saved and loaded back as full instances when read: + +```typescript +import { Reference, z } from "@botpress/runtime"; + +export default new Conversation({ + channel: "*", + state: z.object({ + activeWorkflow: Reference.Workflow("onboarding").optional(), + }), + handler: async ({ state }) => { + // state.activeWorkflow is a full WorkflowInstance when loaded + if (state.activeWorkflow?.status === "completed") { + console.log("Onboarding finished"); + } + }, +}); +``` + ## Bot and user identity The `bot` and `user` objects also expose an `id` property: From 448ce44fba61ccd3a7e4c7962706d763a223359d Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Mon, 6 Apr 2026 11:42:06 -0400 Subject: [PATCH 08/28] docs(adk): fix state context wording, Reference.Workflow example, config:get defaults note --- adk/concepts/configuration.mdx | 2 +- adk/concepts/state.mdx | 13 +++++++------ 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx index a4970037..3a4dd89b 100644 --- a/adk/concepts/configuration.mdx +++ b/adk/concepts/configuration.mdx @@ -164,7 +164,7 @@ This validates your values against the schema and prompts for any missing or inv ### Get and set values -Set and retrieve individual configuration values: +Set and retrieve individual configuration values. Note that `config:get` reads persisted values only and does not resolve schema defaults: ```bash adk config:set supportEmail "help@mycompany.com" diff --git a/adk/concepts/state.mdx b/adk/concepts/state.mdx index 5aa3c124..a951e119 100644 --- a/adk/concepts/state.mdx +++ b/adk/concepts/state.mdx @@ -72,7 +72,7 @@ export default new Conversation({ ### Bot state -Import `bot` from `@botpress/runtime` to access bot-level state from anywhere in your agent: +Import `bot` from `@botpress/runtime` to access bot-level state inside any handler, action, tool, or workflow: ```typescript import { bot } from "@botpress/runtime"; @@ -86,7 +86,7 @@ bot.state.ticketCounter = counter + 1; ### User state -Import `user` from `@botpress/runtime` to access per-user state: +Import `user` from `@botpress/runtime` to access per-user state inside any handler, action, tool, or workflow: ```typescript import { user } from "@botpress/runtime"; @@ -193,7 +193,8 @@ export default new Conversation({ You can store references to workflow instances in state. They are automatically serialized when saved and loaded back as full instances when read: ```typescript -import { Reference, z } from "@botpress/runtime"; +import { Conversation, Reference, z } from "@botpress/runtime"; +import OnboardingWorkflow from "../workflows/onboarding"; export default new Conversation({ channel: "*", @@ -201,9 +202,9 @@ export default new Conversation({ activeWorkflow: Reference.Workflow("onboarding").optional(), }), handler: async ({ state }) => { - // state.activeWorkflow is a full WorkflowInstance when loaded - if (state.activeWorkflow?.status === "completed") { - console.log("Onboarding finished"); + // Start a workflow and store the reference in state + if (!state.activeWorkflow) { + state.activeWorkflow = await OnboardingWorkflow.start({}); } }, }); From 04e5c87f6e9bed5eec2f60d0fe19c4cbca2bd80c Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 11:16:44 -0400 Subject: [PATCH 09/28] =?UTF-8?q?docs(adk):=20apply=20review=20fixes=20?= =?UTF-8?q?=E2=80=94=20description=20wording,=20current-user,=20conversati?= =?UTF-8?q?on=20instance=20access?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- adk/concepts/configuration.mdx | 2 +- adk/concepts/state.mdx | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx index 3a4dd89b..8f7131df 100644 --- a/adk/concepts/configuration.mdx +++ b/adk/concepts/configuration.mdx @@ -13,7 +13,7 @@ import { z, defineConfig } from "@botpress/runtime"; export default defineConfig({ name: "my-agent", - description: "An AI agent built with Botpress ADK", + description: "An AI agent built with the Botpress ADK", defaultModels: { autonomous: "cerebras:gpt-oss-120b", diff --git a/adk/concepts/state.mdx b/adk/concepts/state.mdx index a951e119..fc3dd8d9 100644 --- a/adk/concepts/state.mdx +++ b/adk/concepts/state.mdx @@ -86,7 +86,7 @@ bot.state.ticketCounter = counter + 1; ### User state -Import `user` from `@botpress/runtime` to access per-user state inside any handler, action, tool, or workflow: +Import `user` from `@botpress/runtime` to access current-user state inside any handler, action, tool, or workflow: ```typescript import { user } from "@botpress/runtime"; @@ -100,7 +100,7 @@ user.state.visitCount = (user.state.visitCount || 0) + 1; ### Conversation state -Conversation state is accessed via the `state` parameter in the handler: +Conversation state is accessed via the `state` parameter in the handler or on a Conversation instance: ```typescript export default new Conversation({ @@ -169,7 +169,7 @@ const env = bot.tags.environment; user.tags.role = "admin"; ``` -Conversation tags are accessed via the `conversation` instance in handlers: +You can access conversation tags via the `conversation` instance: ```typescript export default new Conversation({ From 57cc715ab83185bdf0dcc7697594c38b118b4159 Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 11:26:54 -0400 Subject: [PATCH 10/28] docs(adk): update integration config to string shorthand, settings in Control Panel --- adk/concepts/configuration.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx index 8f7131df..0acae251 100644 --- a/adk/concepts/configuration.mdx +++ b/adk/concepts/configuration.mdx @@ -51,8 +51,8 @@ export default defineConfig({ dependencies: { integrations: { - chat: { version: "chat@0.7.7", enabled: true }, - webchat: { version: "webchat@0.3.0", enabled: true }, + chat: "chat@0.7.7", + webchat: "webchat@0.3.0", }, }, }); @@ -197,7 +197,7 @@ adk config:get supportEmail --prod ``` - Agent configuration (`adk config`) is separate from integration configuration. Integration settings like API keys are configured in `agent.config.ts` under `dependencies` or via the Control Panel during `adk dev`. See [Managing Integrations](/adk/managing-integrations) for details. + Agent configuration (`adk config`) is separate from integration configuration. Integration settings like API keys are managed in the Control Panel during `adk dev`. See [Managing Integrations](/adk/managing-integrations) for details. ## Environment variables @@ -224,7 +224,7 @@ const response = await fetch("https://api.example.com/data", { ``` - There is no dedicated secrets API in the ADK. For integration-specific credentials (like OAuth tokens), configure them in `agent.config.ts` under `dependencies` or via the Botpress dashboard. See [Managing Integrations](/adk/managing-integrations) for details. + There is no dedicated secrets API in the ADK. For integration-specific credentials (like OAuth tokens), configure them in the Control Panel during `adk dev` or via the Botpress dashboard. ## Default models @@ -271,11 +271,11 @@ The `dependencies` field declares which integrations your agent uses: ```typescript dependencies: { integrations: { - chat: { version: "chat@0.7.7", enabled: true }, - webchat: { version: "webchat@0.3.0", enabled: true }, - slack: { version: "slack@1.0.0", enabled: true }, + chat: "chat@0.7.7", + webchat: "webchat@0.3.0", + slack: "slack@1.0.0", }, }, ``` -See [Managing Integrations](/adk/managing-integrations) for details on adding, removing, and configuring integrations. +Integration settings (API keys, tokens, etc.) are configured in the Control Panel during `adk dev`, not in `agent.config.ts`. See [Managing Integrations](/adk/managing-integrations) for details. From be41fb7a5d22f37657433c9bb6277537180341ac Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 11:37:05 -0400 Subject: [PATCH 11/28] docs(adk): remove redundant 'optional' from evals description --- adk/concepts/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx index 0acae251..985b31cc 100644 --- a/adk/concepts/configuration.mdx +++ b/adk/concepts/configuration.mdx @@ -108,7 +108,7 @@ export default defineConfig({ Custom event definitions. Each key is an event name, with an optional schema and description. - Optional evaluation settings. + Evaluation settings. Timeout in seconds for idle eval conversations. From c16c8161e743cca49bbee6c0910bbf0899d1b707 Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 13:27:40 -0400 Subject: [PATCH 12/28] docs(adk): move config:get defaults note to Note block --- adk/concepts/configuration.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx index 985b31cc..b382ac58 100644 --- a/adk/concepts/configuration.mdx +++ b/adk/concepts/configuration.mdx @@ -164,7 +164,11 @@ This validates your values against the schema and prompts for any missing or inv ### Get and set values -Set and retrieve individual configuration values. Note that `config:get` reads persisted values only and does not resolve schema defaults: +Set and retrieve individual configuration values: + + + `config:get` reads persisted values only and does not resolve schema defaults. + ```bash adk config:set supportEmail "help@mycompany.com" From 6094fd88a4281c78cb5bb03c49ddc9c47f46f6be Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 13:43:31 -0400 Subject: [PATCH 13/28] docs(adk): remove environment variables section --- adk/concepts/configuration.mdx | 27 --------------------------- 1 file changed, 27 deletions(-) diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx index b382ac58..2cb8db5b 100644 --- a/adk/concepts/configuration.mdx +++ b/adk/concepts/configuration.mdx @@ -204,33 +204,6 @@ adk config:get supportEmail --prod Agent configuration (`adk config`) is separate from integration configuration. Integration settings like API keys are managed in the Control Panel during `adk dev`. See [Managing Integrations](/adk/managing-integrations) for details. -## Environment variables - -You can use `process.env` directly in `agent.config.ts` and throughout your agent code. This is useful for keeping sensitive values like API keys out of your source code: - -```typescript -configuration: { - schema: z.object({ - apiKey: z.string().default(process.env.MY_API_KEY ?? ""), - webhookUrl: z.string().default(process.env.WEBHOOK_URL ?? ""), - }), -}, -``` - -Then access them at runtime via the typed `configuration` import: - -```typescript -import { configuration } from "@botpress/runtime"; - -const response = await fetch("https://api.example.com/data", { - headers: { Authorization: `Bearer ${configuration.apiKey}` }, -}); -``` - - - There is no dedicated secrets API in the ADK. For integration-specific credentials (like OAuth tokens), configure them in the Control Panel during `adk dev` or via the Botpress dashboard. - - ## Default models The `defaultModels` field sets which LLM models your agent uses: From f7164f972f9434ec0c373f01e7d2e59fe42aaaba Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 13:55:00 -0400 Subject: [PATCH 14/28] docs(adk): simplify state intro and user state wording --- adk/concepts/state.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/adk/concepts/state.mdx b/adk/concepts/state.mdx index fc3dd8d9..11911136 100644 --- a/adk/concepts/state.mdx +++ b/adk/concepts/state.mdx @@ -2,14 +2,14 @@ title: State --- -State lets your agent persist data across conversations, users, and the entire bot. The ADK provides three state scopes, each with different lifetimes and access patterns. +State lets your agent store and reuse data across conversations, users, and the entire bot. The ADK provides three types of states, depending on how long you need the data and who should have access to it. ## State scopes | Scope | Lifetime | Access | Defined in | |-------|----------|--------|------------| | Bot | Global, shared across all users and conversations | `bot.state` | `agent.config.ts` | -| User | Per-user, persists across all of a user's conversations | `user.state` | `agent.config.ts` | +| User | Per-user, available across all of a user's conversations | `user.state` | `agent.config.ts` | | Conversation | Per-conversation, scoped to a single conversation | Handler's `state` parameter | Conversation definition | ## Defining state schemas From 54140fb527704da5bb4d85e6c6b9a171f8e6f49d Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 13:57:36 -0400 Subject: [PATCH 15/28] docs(adk): fix highlights, simplify state tracking note --- adk/concepts/state.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/adk/concepts/state.mdx b/adk/concepts/state.mdx index 11911136..33c4d9de 100644 --- a/adk/concepts/state.mdx +++ b/adk/concepts/state.mdx @@ -18,7 +18,7 @@ State lets your agent store and reuse data across conversations, users, and the Define bot and user state schemas in `agent.config.ts`: -```typescript highlight={8-11, 14-18} +```typescript highlight={6-10, 13-17} import { z, defineConfig } from "@botpress/runtime"; export default defineConfig({ @@ -102,7 +102,7 @@ user.state.visitCount = (user.state.visitCount || 0) + 1; Conversation state is accessed via the `state` parameter in the handler or on a Conversation instance: -```typescript +```typescript highlight={3-5, 6, 7-8} export default new Conversation({ channel: "*", state: z.object({ @@ -121,7 +121,7 @@ export default new Conversation({ ``` - State changes are automatically tracked and persisted. You don't need to call a save method: just mutate the state object directly. + State changes are handled automatically. You don't need to call a save method, just update the state object directly. ## Tags From a978f112c1af847e213ee1cbc920a0534a0ed69d Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 14:00:48 -0400 Subject: [PATCH 16/28] docs(adk): remove highlights from state examples --- adk/concepts/state.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/adk/concepts/state.mdx b/adk/concepts/state.mdx index 33c4d9de..310a44db 100644 --- a/adk/concepts/state.mdx +++ b/adk/concepts/state.mdx @@ -18,7 +18,7 @@ State lets your agent store and reuse data across conversations, users, and the Define bot and user state schemas in `agent.config.ts`: -```typescript highlight={6-10, 13-17} +```typescript import { z, defineConfig } from "@botpress/runtime"; export default defineConfig({ @@ -102,7 +102,7 @@ user.state.visitCount = (user.state.visitCount || 0) + 1; Conversation state is accessed via the `state` parameter in the handler or on a Conversation instance: -```typescript highlight={3-5, 6, 7-8} +```typescript export default new Conversation({ channel: "*", state: z.object({ From 0a0ebcc98944f77c9fe864f269c5b4b6792c2138 Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 14:02:49 -0400 Subject: [PATCH 17/28] docs(adk): reduce Managing Integrations mentions to one --- adk/concepts/configuration.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx index 2cb8db5b..5e5451cd 100644 --- a/adk/concepts/configuration.mdx +++ b/adk/concepts/configuration.mdx @@ -201,7 +201,7 @@ adk config:get supportEmail --prod ``` - Agent configuration (`adk config`) is separate from integration configuration. Integration settings like API keys are managed in the Control Panel during `adk dev`. See [Managing Integrations](/adk/managing-integrations) for details. + Agent configuration (`adk config`) is separate from integration configuration. Integration settings like API keys are managed in the Control Panel during `adk dev`. ## Default models @@ -255,4 +255,4 @@ dependencies: { }, ``` -Integration settings (API keys, tokens, etc.) are configured in the Control Panel during `adk dev`, not in `agent.config.ts`. See [Managing Integrations](/adk/managing-integrations) for details. +Integration settings (API keys, tokens, etc.) are configured in the Control Panel during `adk dev`, not in `agent.config.ts`. From 6ca5431580ca75521cb879e7d0550f77d75a34fa Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 14:07:28 -0400 Subject: [PATCH 18/28] docs(adk): fix all highlight line numbers in state examples --- adk/concepts/state.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/adk/concepts/state.mdx b/adk/concepts/state.mdx index 310a44db..ed16094d 100644 --- a/adk/concepts/state.mdx +++ b/adk/concepts/state.mdx @@ -49,7 +49,7 @@ export default defineConfig({ Conversation state is defined on each Conversation definition using the `state` prop: -```typescript highlight={5-8} +```typescript highlight={4-7} import { Conversation, z } from "@botpress/runtime"; export default new Conversation({ @@ -102,7 +102,7 @@ user.state.visitCount = (user.state.visitCount || 0) + 1; Conversation state is accessed via the `state` parameter in the handler or on a Conversation instance: -```typescript +```typescript highlight={6-8} export default new Conversation({ channel: "*", state: z.object({ @@ -132,7 +132,7 @@ Tags are string key-value pairs you can attach to bots, users, conversations, me Define tag schemas in `agent.config.ts`: -```typescript highlight={5-11} +```typescript highlight={4-6, 9-11, 14-16} export default defineConfig({ name: "my-agent", From 620a3601d1d9f1e87800279d6567fd013bc14bc2 Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 14:09:06 -0400 Subject: [PATCH 19/28] docs(adk): system tags code example, simplify state references, fix highlights --- adk/concepts/state.mdx | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/adk/concepts/state.mdx b/adk/concepts/state.mdx index ed16094d..d31b4890 100644 --- a/adk/concepts/state.mdx +++ b/adk/concepts/state.mdx @@ -184,15 +184,21 @@ export default new Conversation({ }); ``` - - System tags (set by integrations, containing `:` in the key) are read-only. You can read them but any writes are silently ignored. - +System tags set by integrations (containing `:` in the key) are read-only: + +```typescript +// You can read system tags +const owner = conversation.tags["webchat:owner"]; + +// But writes to system tags are silently ignored +conversation.tags["webchat:owner"] = "new-value"; // no effect +``` ## State references -You can store references to workflow instances in state. They are automatically serialized when saved and loaded back as full instances when read: +You can store workflow instances in state. They are saved automatically and loaded back as full instances when read: -```typescript +```typescript highlight={5, 9} import { Conversation, Reference, z } from "@botpress/runtime"; import OnboardingWorkflow from "../workflows/onboarding"; @@ -202,7 +208,6 @@ export default new Conversation({ activeWorkflow: Reference.Workflow("onboarding").optional(), }), handler: async ({ state }) => { - // Start a workflow and store the reference in state if (!state.activeWorkflow) { state.activeWorkflow = await OnboardingWorkflow.start({}); } From 32ba3cf81f1d969315d46fd70d8692b971abbfe2 Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 14:14:31 -0400 Subject: [PATCH 20/28] docs(adk): add lead-in text before tags example --- adk/concepts/state.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/adk/concepts/state.mdx b/adk/concepts/state.mdx index d31b4890..35a9bd65 100644 --- a/adk/concepts/state.mdx +++ b/adk/concepts/state.mdx @@ -158,6 +158,8 @@ export default defineConfig({ ### Reading and writing tags +Bot and user tags are read and written the same way as state: + ```typescript import { bot, user } from "@botpress/runtime"; From c7fbcb8f4ea36f5c44a419a67e0f59738ba01410 Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 14:31:33 -0400 Subject: [PATCH 21/28] docs(adk): remove unshipped conversation instance state, add .describe() pattern --- adk/concepts/state.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/adk/concepts/state.mdx b/adk/concepts/state.mdx index 35a9bd65..574778f6 100644 --- a/adk/concepts/state.mdx +++ b/adk/concepts/state.mdx @@ -33,8 +33,8 @@ export default defineConfig({ user: { state: z.object({ - name: z.string().optional(), - department: z.string().optional(), + name: z.string().optional().describe("The user's name"), + department: z.string().optional().describe("The user's department"), visitCount: z.number().default(0), }), }, @@ -42,7 +42,7 @@ export default defineConfig({ ``` - Use `.default()` on your state schema to set initial values. Without defaults, state fields start as `undefined`. + Use `.default()` to set initial values and `.describe()` to document what each field is for. ### Conversation state @@ -100,7 +100,7 @@ user.state.visitCount = (user.state.visitCount || 0) + 1; ### Conversation state -Conversation state is accessed via the `state` parameter in the handler or on a Conversation instance: +Conversation state is accessed via the `state` parameter in the handler: ```typescript highlight={6-8} export default new Conversation({ From 5594929143551e58da5fe975b766330458f12728 Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 15:54:26 -0400 Subject: [PATCH 22/28] docs(adk): fix conversation state highlight off by one --- adk/concepts/state.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adk/concepts/state.mdx b/adk/concepts/state.mdx index 574778f6..ce59bb42 100644 --- a/adk/concepts/state.mdx +++ b/adk/concepts/state.mdx @@ -49,7 +49,7 @@ export default defineConfig({ Conversation state is defined on each Conversation definition using the `state` prop: -```typescript highlight={4-7} +```typescript highlight={5-8} import { Conversation, z } from "@botpress/runtime"; export default new Conversation({ From 9e2e9220ba1e1b6a6c0aeb050a5b7ad0fd17579e Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 16:01:50 -0400 Subject: [PATCH 23/28] docs(adk): remove highlight from tags example --- adk/concepts/state.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adk/concepts/state.mdx b/adk/concepts/state.mdx index ce59bb42..3fe9464a 100644 --- a/adk/concepts/state.mdx +++ b/adk/concepts/state.mdx @@ -132,7 +132,7 @@ Tags are string key-value pairs you can attach to bots, users, conversations, me Define tag schemas in `agent.config.ts`: -```typescript highlight={4-6, 9-11, 14-16} +```typescript export default defineConfig({ name: "my-agent", From b1cdb0ca12299178206c1e6f2d6698a8b2ad5973 Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 16:02:50 -0400 Subject: [PATCH 24/28] docs(adk): fix state references highlight lines --- adk/concepts/state.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adk/concepts/state.mdx b/adk/concepts/state.mdx index 3fe9464a..144a045e 100644 --- a/adk/concepts/state.mdx +++ b/adk/concepts/state.mdx @@ -200,7 +200,7 @@ conversation.tags["webchat:owner"] = "new-value"; // no effect You can store workflow instances in state. They are saved automatically and loaded back as full instances when read: -```typescript highlight={5, 9} +```typescript highlight={7, 11} import { Conversation, Reference, z } from "@botpress/runtime"; import OnboardingWorkflow from "../workflows/onboarding"; From 19e9f0a2253bfba3ddb5c3d464c5efdae93a764b Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 16:03:52 -0400 Subject: [PATCH 25/28] docs(adk): reduce Note blocks in managing configuration section --- adk/concepts/configuration.mdx | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx index 5e5451cd..df2e5a89 100644 --- a/adk/concepts/configuration.mdx +++ b/adk/concepts/configuration.mdx @@ -156,19 +156,11 @@ adk config ✓ Configuration validated successfully ``` -This validates your values against the schema and prompts for any missing or invalid fields. - - - `adk config` requires a `configuration.schema` in your `agent.config.ts`. Without one, you'll see "No configuration schema defined." - +This validates your values against the schema and prompts for any missing or invalid fields. Requires a `configuration.schema` in your `agent.config.ts`. ### Get and set values -Set and retrieve individual configuration values: - - - `config:get` reads persisted values only and does not resolve schema defaults. - +Set and retrieve individual configuration values. Note that `config:get` reads persisted values only and does not resolve schema defaults: ```bash adk config:set supportEmail "help@mycompany.com" From e4d5111bb4f0f686b20f0180a02134148747ffed Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 16:07:43 -0400 Subject: [PATCH 26/28] docs(adk): rename Interactive configuration to Validate configuration --- adk/concepts/configuration.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx index df2e5a89..8c4d69d3 100644 --- a/adk/concepts/configuration.mdx +++ b/adk/concepts/configuration.mdx @@ -142,9 +142,9 @@ Configuration values are defined by the `configuration.schema` in `agent.config. ## Managing configuration -### Interactive configuration +### Validate configuration -Run `adk config` to validate and interactively set all configuration values: +Run `adk config` to validate all configuration values and set any that are missing: ```bash adk config From 890b19c01ae44db1071a574e50611e83d278c719 Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 16:09:14 -0400 Subject: [PATCH 27/28] docs(adk): add Managing Integrations link to config note --- adk/concepts/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx index 8c4d69d3..b072a7b7 100644 --- a/adk/concepts/configuration.mdx +++ b/adk/concepts/configuration.mdx @@ -193,7 +193,7 @@ adk config:get supportEmail --prod ``` - Agent configuration (`adk config`) is separate from integration configuration. Integration settings like API keys are managed in the Control Panel during `adk dev`. + Agent configuration (`adk config`) is separate from integration configuration. Integration settings like API keys are managed in the Control Panel during `adk dev`. See [Managing Integrations](/adk/managing-integrations) for details. ## Default models From be79b7f0dc8e944a6166098e9604d241f7375348 Mon Sep 17 00:00:00 2001 From: Jackson Yu Date: Tue, 7 Apr 2026 16:40:13 -0400 Subject: [PATCH 28/28] docs(adk): remove unnecessary highlight from custom events example --- adk/concepts/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx index b072a7b7..5656da60 100644 --- a/adk/concepts/configuration.mdx +++ b/adk/concepts/configuration.mdx @@ -216,7 +216,7 @@ You can override the model per-call using the `model` prop on `execute()`. Define custom events that your agent can emit and listen to: -```typescript highlight={3-8} +```typescript export default defineConfig({ name: "my-agent", events: {