docs(adk): create State and Configuration concept pages by jacksonyzj · Pull Request #449 · botpress/docs

jacksonyzj · 2026-04-06T14:42:33Z

Summary

Two new concept pages for State and Configuration, filling gaps in the ADK documentation.

Tickets

#	Ticket	Page
1	ADK-304	State
2	ADK-303	Configuration

State page covers

Three state scopes: bot (global), user (per-user), conversation (per-conversation)
Defining schemas in agent.config.ts and Conversation definitions
Reading/writing state in handlers (clarified: only inside runtime context)
Tags definition and read/write for bot, user, conversation
State references with Reference.Workflow()
bot.id and user.id identity accessors

Configuration page covers

Full defineConfig reference with all options (including evals)
configuration runtime import (read-only proxy)
adk config / config:get / config:set with --prod flag (with real CLI output)
Environment variables (process.env in agent.config.ts)
Note: no dedicated secrets API; integration secrets via dashboard
Note: adk config is separate from integration configuration
Note: config:get reads persisted values only, not schema defaults
Default models, custom events, dependencies

Test plan

Preview via Mintlify staging deployment
Live tested adk config, config:set, config:get on real bot
Verified all internal links resolve

…-303)

mintlify · 2026-04-06T14:42:41Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
botpress	🟢 Ready	View Preview	Apr 6, 2026, 2:49 PM

…fig:get defaults note

AugustDG · 2026-04-06T19:15:52Z

adk/concepts/configuration.mdx

+
+export default defineConfig({
+  name: "my-agent",
+  description: "An AI agent built with Botpress ADK",


Suggested change

description: "An AI agent built with Botpress ADK",

description: "An AI agent built with the Botpress ADK",

AugustDG · 2026-04-06T19:21:15Z

adk/concepts/configuration.mdx

+      apiKey: z.string(),
+      maxRetries: z.number().default(3),


suggestion: If this snippet is meant to show only the structure of the config file, we should avoid showing specific schemas.

AugustDG · 2026-04-06T19:21:32Z

adk/concepts/configuration.mdx

+      chat: { version: "chat@0.7.7", enabled: true },
+      webchat: { version: "webchat@0.3.0", enabled: true },


Same as above.

AugustDG · 2026-04-06T19:22:12Z

adk/concepts/configuration.mdx

+```typescript
+import { z, defineConfig } from "@botpress/runtime";
+
+export default defineConfig({


We're missing the evals section

AugustDG · 2026-04-06T19:27:06Z

adk/concepts/configuration.mdx

+    Custom event definitions. Each key is an event name, with an optional schema and description.
+  </ResponseField>
+  <ResponseField name="evals" type="object">
+    Optional evaluation settings.


Most settings are optional, so unless we start mentioning it across the board, I don't think we need it here.

AugustDG · 2026-04-06T20:33:29Z

adk/concepts/configuration.mdx

+```
+
+<Note>
+  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.


Same comment as before.

AugustDG · 2026-04-06T20:55:42Z

adk/concepts/configuration.mdx

+    chat: { version: "chat@0.7.7", enabled: true },
+    webchat: { version: "webchat@0.3.0", enabled: true },
+    slack: { version: "slack@1.0.0", enabled: true },


This is also outdated according to the latest beta release.

AugustDG · 2026-04-06T21:14:05Z

adk/concepts/state.mdx

+
+### User state
+
+Import `user` from `@botpress/runtime` to access per-user state inside any handler, action, tool, or workflow:


Suggested change

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:

AugustDG · 2026-04-06T21:17:12Z

adk/concepts/state.mdx

+user.tags.role = "admin";
+```
+
+Conversation tags are accessed via the `conversation` instance in handlers:


Suggested change

Conversation tags are accessed via the `conversation` instance in handlers:

Conversation tags are accessed via a `conversation` instance:

since you can also do Conversation.get(<id>)

AugustDG · 2026-04-06T21:17:53Z

adk/concepts/state.mdx

+
+### Conversation state
+
+Conversation state is accessed via the `state` parameter in the handler:


Suggested change

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:

chloequijano-botpress · 2026-04-06T21:04:16Z

adk/concepts/state.mdx

+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.


Suggested change

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.

Suggesting a less technical heavy sentence but can reword to fit what you mean

chloequijano-botpress · 2026-04-06T21:06:12Z

adk/concepts/state.mdx

+| 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` |


chloequijano-botpress · 2026-04-06T21:10:24Z

adk/concepts/state.mdx

+
+Define bot and user state schemas in `agent.config.ts`:
+
+```typescript highlight={8-11, 14-18}


Not completely sure what you're highlighting, I think this is off

chloequijano-botpress · 2026-04-06T21:17:03Z

adk/concepts/state.mdx

+
+Conversation state is accessed via the `state` parameter in the handler:
+
+```typescript


can use a highlight here to show what you mean

chloequijano-botpress · 2026-04-06T21:18:13Z

adk/concepts/state.mdx

+```
+
+<Note>
+  State changes are automatically tracked and persisted. You don't need to call a save method: just mutate the state object directly.


Suggested change

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.

chloequijano-botpress · 2026-04-06T21:19:25Z

adk/concepts/state.mdx

+
+Define tag schemas in `agent.config.ts`:
+
+```typescript highlight={5-11}


highlight looks off

chloequijano-botpress · 2026-04-06T21:21:01Z

adk/concepts/state.mdx

+```
+
+<Note>
+  System tags (set by integrations, containing `:` in the key) are read-only. You can read them but any writes are silently ignored.


I think an example code would help here instead of using a note

chloequijano-botpress · 2026-04-06T21:23:13Z

adk/concepts/state.mdx

+
+## 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:


Suggested change

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:

Unless serialized is an important term, this just needs to be reworded

chloequijano-botpress · 2026-04-06T21:24:07Z

adk/concepts/state.mdx

+
+You can store references to workflow instances in state. They are automatically serialized when saved and loaded back as full instances when read:
+
+```typescript


instead of commenting in the code, can highlight whats relevant

chloequijano-botpress · 2026-04-06T21:29:23Z

adk/concepts/configuration.mdx

+},
+```
+
+See [Managing Integrations](/adk/managing-integrations) for details on adding, removing, and configuring integrations.


the managing integration page is mentioned like 3 times in this guide. Could limit it to one and maybe cut how often we mention it.

docs(adk): create State and Configuration concept pages (ADK-304, ADK…

b7fcda1

…-303)

mintlify bot deployed to staging April 6, 2026 14:49 View deployment

docs(adk): fix default models to match adk init output

2caa13c

mintlify bot deployed to staging April 6, 2026 14:56 View deployment

docs(adk): add real CLI output, clarify adk config vs integration config

ae3222a

mintlify bot deployed to staging April 6, 2026 15:05 View deployment

docs(adk): add env variables section, evals config option (ADK-303)

89ebacc

mintlify bot deployed to staging April 6, 2026 15:16 View deployment

docs(adk): minor wording fixes in state and configuration pages

ae07f2a

mintlify bot deployed to staging April 6, 2026 15:21 View deployment

docs(adk): improve env variables section with practical API key example

f076eb2

mintlify bot deployed to staging April 6, 2026 15:26 View deployment

docs(adk): add state references section (ADK-304)

279df58

mintlify bot deployed to staging April 6, 2026 15:28 View deployment

docs(adk): fix state context wording, Reference.Workflow example, con…

448ce44

…fig:get defaults note

mintlify bot deployed to staging April 6, 2026 15:44 View deployment

jacksonyzj marked this pull request as ready for review April 6, 2026 15:52

jacksonyzj requested review from adkah and chloequijano-botpress as code owners April 6, 2026 15:52

jacksonyzj requested review from a team and aj-botpress April 6, 2026 15:52

AugustDG reviewed Apr 6, 2026

View reviewed changes

chloequijano-botpress reviewed Apr 6, 2026

View reviewed changes

	description: "An AI agent built with Botpress ADK",
	description: "An AI agent built with the Botpress ADK",

		chat: { version: "chat@0.7.7", enabled: true },
		webchat: { version: "webchat@0.3.0", enabled: true },


		### User state

		Import `user` from `@botpress/runtime` to access per-user state inside any handler, action, tool, or workflow:

	Conversation tags are accessed via the `conversation` instance in handlers:
	Conversation tags are accessed via a `conversation` instance:


		### Conversation state

		Conversation state is accessed via the `state` parameter in the handler:

	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.

	\| 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` \|


		Define bot and user state schemas in `agent.config.ts`:

		```typescript highlight={8-11, 14-18}


		Conversation state is accessed via the `state` parameter in the handler:

		```typescript

	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.


		Define tag schemas in `agent.config.ts`:

		```typescript highlight={5-11}


		## 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 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:

Conversation

jacksonyzj commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Tickets

State page covers

Configuration page covers

Test plan

Uh oh!

mintlify bot commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chloequijano-botpress Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jacksonyzj commented Apr 6, 2026 •

edited

Loading

mintlify bot commented Apr 6, 2026 •

edited

Loading

chloequijano-botpress Apr 6, 2026 •

edited

Loading