• Actions & Tools (reusable functions and AI-callable tools)
• Workflows (long-running, resumable processes)
• Conversations (message handling)
• Tables (data storage with semantic search)
• Files (file storage with semantic search)
• Knowledge Bases (RAG implementation)
• Triggers (event-driven automation)
• Zai (production-ready LLM utility library for common AI operations)

src/

/                      # Project root
├── src/
│   ├── actions/       # Strongly-typed functions → auto-registered
│   ├── tools/         # AI-callable tools → available via execute()
│   ├── workflows/     # Long-running processes → resumable/scheduled
│   ├── conversations/ # Message handlers → routes by channel
│   ├── tables/        # Database schemas → auto-created with search
│   ├── triggers/      # Event handlers → subscribe to events
│   ├── knowledge/     # Knowledge bases → RAG with semantic search
│   └── utils/         # Shared helpers (not auto-registered)
└── agent.config.ts    # Bot configuration (includes integrations)

Note:

dependencies.json

was removed in ADK 1.9+. All configuration including integrations now lives in

agent.config.ts

.

Critical: Files outside

src/

are not discovered. Location = behavior.

• "How do I create an Action/Tool/Workflow/Conversation?"
• "What is the difference between X and Y?"
• "Show me an example of..."
• "How do I configure...?"
• "What's the CLI command for...?"
• "How do I use the Context API?"
• "How do I call integration actions?"
• "How do I use Zai for [extract/check/label/etc]?"
• "What are the best practices for...?"
• "How do I avoid common mistakes?"
• "How do I handle ticket assignment/escalation?"

• "How do I create a workflow?"
• "What's the difference between Actions and Tools?"
• "Show me an example of using Zai"
• "What are best practices for state management?"
• "How do I fix this error?"
• "What's the pattern for X?"

1. Find relevant files - Use Glob to discover documentation:

   pattern: **/references/*.md

2. Search for keywords - Use Grep to find relevant content:

   pattern: <keyword from user question>
   path: <path to references directory from step 1>
   output_mode: files_with_matches

3. Read the files - Use Read to load relevant documentation
4. Provide answer with:
   • Concise explanation
   • Code examples from the references
   • File references with line numbers (e.g., "From references/actions.md:215")
   • Common pitfalls if relevant
   • Related topics for further reading

• actions.md - Actions with strong typing and validation
• tools.md - AI-callable tools and Autonomous namespace
• workflows.md - Workflows and step-based execution
• conversations.md - Conversation handlers and message routing
• triggers.md - Event-driven automation
• messages.md - Sending messages and events

• tables.md - Data storage with semantic search
• files.md - File storage and management
• knowledge-bases.md - RAG implementation
• zai-complete-guide.md - Complete ZAI developer guide
• zai-agent-reference.md - Quick ZAI reference

• agent-config.md - Bot configuration and state management
• model-configuration.md - AI model configuration reference
• context-api.md - Runtime context access
• integration-actions.md - Using integration actions
• tags.md - Entity tags for bot, user, conversation, and workflow
• cli.md - Complete CLI command reference
• mcp-server.md - MCP server for AI assistants

• frontend/botpress-client.md - Using @botpress/client in frontends
• frontend/calling-actions.md - Calling bot actions from frontend
• frontend/type-generation.md - Type-safe integration with generated types
• frontend/authentication.md - Authentication with PATs

• Actions/Tools/Workflows:

  myAction.ts

  ,

  searchDocs.ts

  (camelCase)
• Tables:

  Users.ts

  ,

  Orders.ts

  (PascalCase)
• Conversations/Triggers:

  chat.ts

  ,

  slack.ts

  (lowercase)

• "What is an Action?"
• "How do I create my first workflow?"
• "What's the difference between Actions and Tools?"

• "How do I access the Botpress client?"
• "How do I use citations in RAG?"
• "What's the syntax for searchable table columns?"
• "How do I call a Slack integration action?"
• "How do I use Zai to extract structured data?"
• "How do I validate content with Zai?"

• "How do I add guardrails to prevent hallucinations?"
• "How do I implement admin authentication?"
• "How do I add logging and observability?"
• "How do I compose multiple extensions?"
• "How do I manage context in async tool handlers?"

• "Why am I getting 'Cannot destructure property' error?"
• "How do I fix import errors?"
• "What's wrong with my workflow state access?"

• "What are common mistakes to avoid?"
• "How should I structure my project?"
• "What's the recommended pattern for X?"

1. Start with a concise explanation - Answer the core question directly
2. Provide working code examples - Use examples from references or create based on patterns
3. Include file references - Cite documentation (e.g., "From actions.md:215")
4. Highlight common pitfalls - Reference the troubleshooting section if relevant
5. Security & best practices - Mention security considerations when applicable
6. Link to related topics - Suggest further reading or related concepts

Actions are strongly-typed functions that can be called from anywhere in your bot.

**Example:**
[code example]

**Common Pitfall:** Remember to destructure `input` first (see troubleshooting section)

**Related:** You can convert Actions to Tools using `.asTool()` - see the "When to Use What" decision tree.

**Next Steps:** Create your action in `src/actions/myAction.ts` and it will be auto-registered.