---
slug: "agentforce-planner-bundle-builder-skill"
source_type: "skill_md"
source_url: "https://cdn.jsdelivr.net/gh/dylandersen/agentforce-planner-bundle-builder-skill@main/SKILL.md"
repo: "https://github.com/dylandersen/agentforce-planner-bundle-builder-skill"
source_file: "SKILL.md"
branch: "main"
---
---
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](https://github.com/dylandersen/agentforce-planner-bundle-builder-skill/blob/HEAD/references/planner-bundle-guide.md)**: 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