@botpress/adk-cli 1.19.0-beta.4 → 1.19.0-beta.6

package/dist/tags-46td3qrg.md

@@ -0,0 +1,516 @@
+# Tags
+
+Tags are key-value pairs that can be attached to bots, users, conversations, and workflows. They provide a flexible way to track metadata, categorize entities, and store cross-handler state.
+
+## Basic Concepts
+
+### What are Tags?
+
+- **Key-value pairs**: String keys with string values
+- **Entity-scoped**: Available on bot, user, conversation, and workflow
+- **Schema-defined**: Must be declared in `agent.config.ts`
+- **Automatically persisted**: Changes are tracked and saved automatically
+- **System vs Custom**: System tags (with `:`) are read-only
+
+### Tag Types
+
+| Type | Example Key | Description |
+|------|-------------|-------------|
+| **Custom** | `tier`, `region` | User-defined, read-write |
+| **System** | `webchat:owner` | Integration-managed, read-only |
+
+## Defining Tags
+
+Tags must be defined in your `agent.config.ts` to be persisted:
+
+### User Tags
+
+```typescript
+import { defineConfig, z } from "@botpress/runtime";
+
+export default defineConfig({
+  name: "my-bot",
+
+  user: {
+    // User state (mutable object data)
+    state: z.object({
+      preferences: z.object({}).passthrough(),
+    }),
+
+    // User tags (key-value pairs for categorization)
+    // Tags are defined as { title: string, description?: string } objects, NOT Zod schemas
+    tags: {
+      tier: { title: "Subscription Tier", description: "User subscription level" },
+      region: { title: "Region", description: "User geographic region" },
+      source: { title: "Acquisition Source" },
+      referralCode: { title: "Referral Code" },
+    },
+  },
+});
+```
+
+### Conversation Tags
+
+```typescript
+export default defineConfig({
+  name: "my-bot",
+
+  conversation: {
+    tags: {
+      category: { title: "Category" },
+      priority: { title: "Priority", description: "Conversation priority level" },
+      assignedTo: { title: "Assigned To" },
+      department: { title: "Department" },
+    },
+  },
+});
+```
+
+### Bot Tags
+
+```typescript
+export default defineConfig({
+  name: "my-bot",
+
+  bot: {
+    state: z.object({
+      version: z.number().default(1),
+    }),
+
+    tags: {
+      environment: { title: "Environment", description: "Deployment environment" },
+      region: { title: "Region" },
+      version: { title: "Version" },
+    },
+  },
+});
+```
+
+### Workflow Tags
+
+```typescript
+export default defineConfig({
+  name: "my-bot",
+
+  workflow: {
+    tags: {
+      type: { title: "Workflow Type" },
+      priority: { title: "Priority" },
+      createdBy: { title: "Created By" },
+    },
+  },
+});
+```
+
+## Using Tags
+
+### In Conversations
+
+```typescript
+import { Conversation, user } from "@botpress/runtime";
+
+export default new Conversation({
+  channel: "webchat.channel",
+
+  // conversation is provided as a handler parameter — no need for context.get()
+  async handler({ message, conversation }) {
+    // Read user tags
+    console.log(`User tier: ${user.tags.tier}`);
+    console.log(`User region: ${user.tags.region}`);
+
+    // Set user tags
+    user.tags.tier = "pro";
+    user.tags.source = "website";
+
+    // Read conversation tags
+    console.log(`Category: ${conversation.tags.category}`);
+
+    // Set conversation tags
+    conversation.tags.priority = "high";
+    conversation.tags.department = "support";
+
+    // Conditional logic based on tags
+    if (user.tags.tier === "enterprise") {
+      // Priority handling for enterprise users
+      conversation.tags.priority = "urgent";
+    }
+  },
+});
+```
+
+### In Workflows
+
+```typescript
+import { Workflow, z, bot } from "@botpress/runtime";
+
+export const ProcessingWorkflow = new Workflow({
+  name: "processing",
+  input: z.object({ userId: z.string() }),
+
+  async handler({ input, workflow, step }) {
+    // Set workflow tags
+    workflow.tags.type = "data-processing";
+    workflow.tags.priority = "high";
+
+    // Access bot tags
+    console.log(`Environment: ${bot.tags.environment}`);
+
+    await step("process", async () => {
+      // Processing logic
+    });
+
+    return { success: true };
+  },
+});
+```
+
+### In Actions
+
+```typescript
+import { Action, z, user, context } from "@botpress/runtime";
+
+export default new Action({
+  name: "upgradeUser",
+  input: z.object({
+    newTier: z.enum(["free", "pro", "enterprise"]),
+  }),
+  output: z.object({ success: z.boolean() }),
+
+  async handler({ input }) {
+    const oldTier = user.tags.tier;
+    const conversation = context.get("conversation", { optional: true });
+
+    // Update user tag
+    user.tags.tier = input.newTier;
+
+    // Log the upgrade in conversation
+    if (conversation) {
+      conversation.tags.category = "upgrade";
+    }
+
+    console.log(`Upgraded user from ${oldTier} to ${input.newTier}`);
+
+    return { success: true };
+  },
+});
+```
+
+## Tags vs State
+
+Understanding when to use tags versus state:
+
+| Aspect | Tags | State |
+|--------|------|-------|
+| **Structure** | Flat key-value pairs | Nested objects |
+| **Types** | Strings only | Any type (objects, arrays, numbers) |
+| **Use case** | Categorization, filtering | Complex data storage |
+| **Queryable** | Yes (via API) | Limited |
+| **Size** | Small values | Larger structures |
+
+### When to Use Tags
+
+```typescript
+// ✅ Good for tags - simple categorization
+user.tags.tier = "pro";
+user.tags.region = "us-east";
+conversation.tags.priority = "high";
+
+// ❌ Bad for tags - complex data belongs in state
+user.tags.preferences = JSON.stringify({ theme: "dark" }); // Don't do this!
+```
+
+### When to Use State
+
+```typescript
+// ✅ Good for state - complex structures
+user.state.preferences = {
+  theme: "dark",
+  notifications: true,
+  language: "en",
+};
+
+user.state.history = [
+  { action: "login", timestamp: new Date() },
+  { action: "purchase", timestamp: new Date() },
+];
+```
+
+## System Tags
+
+System tags are managed by integrations and are **read-only**. They contain a colon (`:`) in their key.
+
+### Common System Tags
+
+```typescript
+// Webchat system tags (read-only)
+console.log(user.tags["webchat:owner"]); // User who initiated webchat
+console.log(conversation.tags["webchat:sessionId"]); // Session identifier
+
+// Integration-specific system tags
+console.log(user.tags["slack:userId"]); // Slack user ID
+console.log(conversation.tags["discord:channelId"]); // Discord channel
+```
+
+### System Tag Behavior
+
+```typescript
+// System tags are silently ignored when you try to set them
+user.tags["webchat:owner"] = "new-value"; // No error, but no effect
+
+// Only custom tags (without ':') can be modified
+user.tags.tier = "enterprise"; // ✅ Works
+user.tags.customField = "value"; // ✅ Works
+```
+
+## Advanced Patterns
+
+### Tag-Based Routing
+
+```typescript
+import { Conversation, conversation, user } from "@botpress/runtime";
+
+export default new Conversation({
+  channel: "webchat.channel",
+
+  async handler({ message, execute }) {
+    // Route based on conversation priority
+    const priority = conversation.tags.priority;
+
+    if (priority === "urgent") {
+      // Fast-track urgent conversations
+      await execute({
+        instructions: "This is an urgent request. Prioritize resolution.",
+        model: "openai:gpt-4o", // Use best model
+      });
+    } else {
+      await execute({
+        instructions: "Help the user with their request.",
+        model: "openai:gpt-4o-mini", // Cost-efficient model
+      });
+    }
+  },
+});
+```
+
+### Tag-Based Analytics
+
+```typescript
+import { Trigger } from "@botpress/runtime";
+import { AnalyticsTable } from "../tables/Analytics";
+
+export default new Trigger({
+  name: "trackConversation",
+  events: ["conversation.ended"],
+
+  async handler({ event }) {
+    const { conversationId, tags } = event.payload;
+
+    // Store conversation metrics by tags
+    await AnalyticsTable.createRows({
+      rows: [
+        {
+          conversationId,
+          category: tags.category || "uncategorized",
+          priority: tags.priority || "normal",
+          department: tags.department || "general",
+          timestamp: new Date(),
+        },
+      ],
+    });
+  },
+});
+```
+
+### Progressive Tag Collection
+
+```typescript
+import { Conversation, user, adk } from "@botpress/runtime";
+
+export default new Conversation({
+  channel: "webchat.channel",
+
+  async handler({ message }) {
+    // Infer and set tags from conversation
+    if (!user.tags.region && message?.type === "text") {
+      const region = await adk.zai.extract(
+        message.payload.text,
+        z.string().optional(),
+        { instructions: "Extract geographic region if mentioned" }
+      );
+
+      if (region) {
+        user.tags.region = region;
+      }
+    }
+
+    // Set source tag if not already set
+    if (!user.tags.source) {
+      user.tags.source = "webchat";
+    }
+  },
+});
+```
+
+### Tag Inheritance in Workflows
+
+```typescript
+import { Workflow, z, user } from "@botpress/runtime";
+
+export const SupportWorkflow = new Workflow({
+  name: "support",
+  input: z.object({
+    conversationId: z.string(),
+    issue: z.string(),
+  }),
+
+  async handler({ input, workflow, step }) {
+    // Inherit priority from user tier
+    const tier = user.tags.tier;
+
+    if (tier === "enterprise") {
+      workflow.tags.priority = "high";
+    } else if (tier === "pro") {
+      workflow.tags.priority = "normal";
+    } else {
+      workflow.tags.priority = "low";
+    }
+
+    // Set workflow type
+    workflow.tags.type = "support-ticket";
+
+    await step("process", async () => {
+      // Processing based on priority
+    });
+
+    return { processed: true };
+  },
+});
+```
+
+## Best Practices
+
+### 1. Use Descriptive Tag Names
+
+```typescript
+// ✅ Good - clear purpose
+tags: {
+  subscriptionTier: { title: "Subscription Tier", description: "User subscription level" },
+  acquisitionChannel: { title: "Acquisition Channel" },
+  supportPriority: { title: "Support Priority" },
+}
+
+// ❌ Bad - unclear
+tags: {
+  t: { title: "T" },
+  lvl: { title: "Lvl" },
+  p: { title: "P" },
+}
+```
+
+### 2. Use Enums for Constrained Values
+
+```typescript
+// ✅ Good - descriptive titles
+tags: {
+  status: { title: "Account Status", description: "Active, inactive, or suspended" },
+  tier: { title: "Subscription Tier", description: "Free, pro, or enterprise" },
+}
+
+// ❌ Bad - missing descriptions
+tags: {
+  status: { title: "Status" }, // Unclear what values are expected
+}
+```
+
+### 3. Document Tag Purposes
+
+```typescript
+export default defineConfig({
+  user: {
+    tags: {
+      tier: { title: "Subscription Tier", description: "Customer subscription level for feature gating" },
+      region: { title: "Region", description: "Geographic region for compliance and routing" },
+      acquisitionSource: { title: "Acquisition Source", description: "How the user discovered the bot" },
+    },
+  },
+});
+```
+
+### 4. Set Tags Early
+
+```typescript
+// Set identification tags early in the conversation
+async handler({ message, type }) {
+  if (type === "conversation_started") {
+    // Set source immediately
+    conversation.tags.source = "webchat";
+    conversation.tags.startedAt = new Date().toISOString();
+  }
+}
+```
+
+### 5. Use Tags for Filtering, Not Storage
+
+```typescript
+// ✅ Good - tags for filtering/categorization
+user.tags.tier = "enterprise";
+conversation.tags.category = "billing";
+
+// ❌ Bad - storing complex data in tags
+user.tags.preferences = JSON.stringify({ notifications: true }); // Use state instead
+```
+
+## Troubleshooting
+
+### Tags Not Persisting
+
+1. **Check schema definition**: Tags must be defined in `agent.config.ts`
+2. **Verify tag key**: Custom tags cannot contain `:`
+3. **Check value type**: Tags only accept string values
+
+```typescript
+// ✅ Correct
+user.tags.tier = "pro"; // String value
+
+// ❌ Wrong - will be ignored or cause errors
+user.tags.count = 5; // Number (should be string)
+user.tags.active = true; // Boolean (should be string)
+```
+
+### System Tags Appearing Read-Only
+
+System tags (containing `:`) are managed by integrations:
+
+```typescript
+// These are read-only - modifications are silently ignored
+user.tags["webchat:owner"] = "new"; // No effect
+conversation.tags["slack:channel"] = "new"; // No effect
+
+// Only custom tags can be modified
+user.tags.myCustomTag = "value"; // ✅ Works
+```
+
+### Tag Not in Schema Error
+
+If you see errors about undefined tags, add them to your config:
+
+```typescript
+// Before: Tag not in schema
+user.tags.newTag = "value"; // Warning: Tag not defined
+
+// Fix: Add to agent.config.ts
+export default defineConfig({
+  user: {
+    tags: {
+      newTag: { title: "New Tag" }, // Now it will persist
+    },
+  },
+});
+```
+
+## See Also
+
+- **[Agent Configuration](./agent-config.md)** - Full agent.config.ts reference
+- **[Conversations](./conversations.md)** - Using tags in conversation handlers
+- **[Workflows](./workflows.md)** - Workflow tags and state management
+- **[Context API](./context-api.md)** - Accessing bot, user, conversation context