name: Agentforce Planner Bundle Builder
description: Comprehensive guide for building, configuring, and deploying Legacy Agentforce GenAiPlannerBundles. Use when creating Agentforce agents, working with GenAiPlannerBundles, GenAiPlugins, or GenAiFunctions, understanding Agentforce architecture, configuring topics/actions/schemas, deploying planner bundles, creating Service or Employee agents, or troubleshooting bundle deployment issues.

Agentforce Planner Bundle Builder

This skill provides comprehensive knowledge for building Agentforce Planner Bundles - the core configuration files that define AI agent capabilities, behavior, and structure in Salesforce Agentforce.

Quick Reference

Architecture: Three-tier system
1. GenAiFunctions → Define reusable actions (Flows/Apex/standard actions)
2. GenAiPlugins → Define reusable topics (reference functions)
3. GenAiPlannerBundles → Create agents (reference plugins, create local copies)

Deployment Order (CRITICAL):
1. GenAiFunctions (no dependencies)
2. GenAiPlugins (depends on functions)
3. GenAiPlannerBundles (depends on plugins and functions)

Agent Types:
- Service Agents: Customer-facing (CustomerWebClient surface, SvcCopilotTmpl__ prefix)
- Employee Agents: Internal-facing (Messaging only, EmployeeCopilot__ prefix)

Core Workflow

Building an Agent

1. Create GenAiFunction: Define action with invocation target and schemas
2. Create GenAiPlugin: Define topic with scope, instructions, and function references
3. Create GenAiPlannerBundle: Link plugins, create local copies with unique IDs, configure surfaces

Key Concepts

• Local Copies: Bundles create local copies of plugins/functions with unique IDs
• Source Attribute: Links bundle copies back to original plugin/function names
• Attribute Mappings: Share data between actions via planner variables
• Rule Expressions: Conditionally enable topics/actions based on context
• Schemas: Define input/output structure with Lightning types and PII flags

Detailed Reference

For comprehensive information, see:
- Planner Bundle Guide: Complete reference covering architecture, components, patterns, best practices, deployment, and troubleshooting

Common Tasks

Creating a New Agent

1. Identify agent type (Service vs Employee)
2. Create required GenAiFunctions
3. Create GenAiPlugins that reference functions
4. Create GenAiPlannerBundle that links plugins
5. Configure surfaces, mappings, and rules
6. Deploy in correct order

Adding a Topic to Existing Agent

1. Create GenAiFunction(s) for topic actions
2. Create GenAiPlugin referencing functions
3. Add localTopicLinks to bundle
4. Create localTopics entry (copy plugin, add unique ID)
5. Create localActions entries (copy functions, add unique IDs)
6. Link actions to topic via localActionLinks
7. Copy schemas to localActions/{TopicName}_{ID}/{ActionName}_{ID}/

Schema Design

• Use Lightning types: lightning__textType, lightning__booleanType, lightning__dateType, lightning__numberType
• Mark PII fields: lightning:isPII: true
• Mark user input: copilotAction:isUserInput: true
• Set unevaluatedProperties: false for strict validation

Troubleshooting

Common issues:
- Missing invocation targets → Ensure Flow/Apex exists
- Schema mismatches → Verify schema matches Flow/Apex parameters
- Deployment order errors → Deploy Functions → Plugins → Bundles
- Missing source references → Ensure source matches plugin/function developerName

Best Practices

1. Topics: Group related actions, clear scope, logical separation
2. Instructions: Be specific, avoid hardcoding, trust components
3. Schemas: Mark PII, use user input flags, clear descriptions
4. Actions: Require confirmation for critical actions, show progress for long operations
5. Variables: Consistent naming, share data via attribute mappings
6. Rules: Keep simple, document purpose, test thoroughly

Templates

Ready-to-use templates are available in assets/templates/:
- genAiFunction-template.xml - GenAiFunction metadata template
- genAiPlugin-template.xml - GenAiPlugin metadata template
- genAiPlannerBundle-template.xml - Complete bundle template with all components
- schema-input-template.json - Input schema template with common patterns
- schema-output-template.json - Output schema template
- knowledge-search-action-template.xml - Knowledge search action example

Use these templates as starting points when creating new components.

When to Load Reference Guide

Load references/planner-bundle-guide.md when you need:
- Detailed XML structure examples
- Complete component reference
- Advanced patterns and use cases
- Deployment troubleshooting
- Agent type determination logic
- Complete workflow examples