Agentforce Agent Creation

Agentforce Agent Creation

Use this skill when the work is standing up a new Agentforce agent or troubleshooting one that will not activate, will not appear to users, or behaves unexpectedly after deployment. This skill covers the agent definition, agent user, channel assignment, instructions and system prompt, activation, and lifecycle across environments. It does not cover subagent boundary design or action contract design — those have their own skills.

Agentforce is Salesforce's autonomous AI agent platform (formerly Einstein Copilot). Agents are powered by a reasoning engine (GenAiPlannerBundle) layered on top of a Bot/BotVersion shell that governs the channel surface. A fully working agent requires the right platform prerequisites, a correctly configured agent definition, at least one subagent with one action, and a channel to surface it on. Missing any layer produces silent failures or a blank agent panel.

Terminology. This skill leads with subagent because that is the current product term — beginning in April 2026, agent topics are called subagents, with no change to functionality. It deliberately keeps topic in metadata and API names (GenAiPlugin is still documented as "an agent topic"), in the agent-topic-design skill path, and in search keywords — those did not change, and readers arriving with the older vocabulary still need to find this skill.

Before Starting

Gather this context before working on anything in this domain:

• Is Einstein enabled? Navigate to Setup > Einstein Setup and confirm the Einstein toggle is On.
• Is the Agentforce toggle active? Setup > Agentforce Agents must show the Agentforce feature toggle as Active.
• Is the Einstein Trust Layer configured? Zero-data-retention and grounding settings affect what data the agent can access. Review with agentforce/einstein-trust-layer if not confirmed.
• Which channel will the agent surface on? Embedded Service, Messaging for Web, Experience Cloud Embedded Messaging, or Agent API each have different prerequisites.
• Does a dedicated agent user (EinsteinServiceAgent User or equivalent) exist with the correct permission set?

Core Concepts

The Agent Is A Layered Metadata Bundle

An Agentforce agent is not a single record. It consists of three linked metadata layers:

• Bot + BotVersion — the top-level shell and channel routing definition. Provides the conversation container (session, language, fallback).
• GenAiPlannerBundle (API v64+; GenAiPlanner in API v60–63) — the reasoning engine. Attaches to the BotVersion and gives the bot agent-level reasoning capability. Deploying BotVersion without GenAiPlannerBundle produces a chatbot, not an agent.
• GenAiPlugin (Subagents) and GenAiFunction (Actions) — the capability payload. Subagents define jobs the agent performs; actions define tools within those jobs.

All layers must be deployed together and remain consistent. When retrieving or deploying agent metadata, treat the bundle as one unit.

Agent User Is A Separate Runtime Identity

Every Agentforce agent runs under a dedicated system user — the EinsteinServiceAgent User. This user must exist, have the Einstein Agent User permission set assigned, and be selected (not typed) from the dropdown in the Agent User field during setup. The agent's record access at runtime is governed by this user's profile and permission set assignments.

Lifecycle Has Three States

• Draft — the agent is under construction or has been deactivated. Not accessible to end users on any channel.
• Active — the agent is live and accessible on its assigned channel. Activation is a deliberate, explicit click action in Agentforce Builder.
• Inactive — a previously active agent that has been deactivated. Previous BotVersions are retained for rollback.

Activation does not carry over between environments. An agent deployed from sandbox to production via Metadata API or change set arrives in Inactive state and must be explicitly activated in production before it serves users.

Channel Assignment Is A Separate Configuration Step

Creating and activating an agent in Setup does not make it available to users. The agent must be assigned to a channel surface:

• Embedded Service Deployment — surfaces the agent in a web chat widget on Experience Cloud or an external site.
• Messaging for In-App and Web — routes inbound messaging sessions to the agent through Omni-Channel with a routing configuration pointing at the agent.
• Agent API — exposes the agent over a REST API for custom or third-party channel integration.

Each channel type has its own prerequisites. Embedded Service requires a published Experience Cloud site. Messaging requires Omni-Channel, a routing configuration, and a queue with the agent user as a member.

Common Patterns

Mode 1: Create A New Agent End-To-End

When to use: Greenfield agent creation — nothing exists yet.

How it works:

1. Confirm prerequisites: Einstein On, Agentforce toggle On, Trust Layer reviewed.

2. Setup > Agentforce Agents > + New Agent. Select the appropriate template (Agentforce Service Agent for Service Cloud; custom agent for other use cases).

3. Fill in the required fields:

   Field	Notes
   Label and API Name	The API Name is immutable after creation; choose it with the same deliberateness as a custom object API Name.
   Role	Natural-language description of the agent's job and persona (e.g., "customer service representative for a hospitality company"). Becomes part of the system context fed to the reasoning engine.
   Company	Organizational context included in system instructions.
   Agent User	Select the EinsteinServiceAgent User from the dropdown; do not type manually.
   Enhanced Event Logs	Enable for conversation tracing during testing and audit.

4. Add subagents and actions via Agentforce Builder (see agentforce/agent-topic-design and agentforce/agent-actions).

5. Review Agent Instructions — the system-prompt persona block that shapes tone, constraints, and fallback behavior. Specific, deterministic instructions produce more predictable agent behavior than vague persona statements.

6. Click Activate in Agentforce Builder (upper-right corner). The agent transitions from Draft to Active.

7. Assign to channel. For Embedded Service: Setup > Embedded Service Deployments > New (Messaging for In-App and Web). Configure the routing rule to target the agent. Add the Embedded Messaging component in Experience Builder and publish the site. Allow up to 10 minutes for changes to propagate.

Mode 2: Review Or Audit An Existing Agent Configuration

When to use: An agent is behaving unexpectedly, routing incorrectly, or failing silently.

How it works:

1. Confirm the agent is Active (Setup > Agentforce Agents — check the status indicator).
2. Confirm the Agent User has the correct permission set and can access the records the agent needs at runtime.
3. Open the agent in Agentforce Builder. Review:
   • Agent instructions and system prompt for contradictions or vague scope.
   • Subagent classification descriptions — do they match the queries being tested?
   • Action availability within each subagent and whether action configurations are complete.
4. Use the Conversation Preview panel in Agentforce Builder to reproduce the failure interactively.
5. For production agents, review Enhanced Event Logs conversation records to inspect the prompt and response pipeline.
6. Verify the channel configuration has not drifted. If a Flow routes to the agent, confirm the flow targets the correct agent name and the flow version is Active.

Mode 3: Troubleshoot Agent Not Appearing To Users

When to use: The agent is Active in Setup but users see no chat widget or the agent does not respond.

How it works:

1. Confirm the agent is Active — not Draft or Inactive.
2. Confirm the channel deployment has been published or re-published after the agent was activated. Publishing order matters; an Embedded Service deployment published before activation will not carry the active agent.
3. If using Experience Cloud, republish the Experience Cloud site after any Embedded Messaging configuration change.
4. If the "New Agent" button is missing in Setup or agent changes are not reflecting, refresh the page — this is a known platform UI state issue.
5. If routing flows reference the agent but the agent name does not appear in the flow dropdown, deactivate and reactivate the Agentforce toggle, then retry.
6. Confirm the EinsteinServiceAgent User is assigned to the channel's Omni-Channel queue.
7. Allow up to 10 minutes for embedded deployment changes to propagate through CDN edge caches.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the org edition, relevant objects, and current configuration state
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
4. Validate — run the skill's checker script and verify against the Review Checklist below
5. Document — record any deviations from standard patterns and update the template if needed

Review Checklist

Run through these before marking work in this area complete:

• Einstein is enabled (Einstein Setup toggle is On).
• Agentforce feature toggle is Active in Setup > Agentforce Agents.
• Agent definition has a clear Role description and Company context in system instructions.
• Agent API Name is finalized before creation — it cannot be changed afterward.
• EinsteinServiceAgent User is assigned to the agent using the dropdown picker (not typed).
• The agent user has the Einstein Agent User permission set assigned.
• At least one subagent with at least one action exists before activation.
• Agent is in Active state (not Draft or Inactive).
• Channel deployment (Embedded Service or Messaging) has been published after agent activation.
• Enhanced Event Logs are enabled for post-launch conversation audit.
• If deploying to production, activation has been performed manually in the target org after metadata deployment.
• Einstein Trust Layer configuration has been reviewed for data access and grounding patterns.

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Agent API Name is permanent — the API Name assigned at creation cannot be changed. A wrong API Name requires creating a new agent from scratch and migrating all subagents and actions. Choose it carefully before the first save.
2. Activation does not transfer between environments — deploying agent metadata via Metadata API or a change set leaves the agent in Inactive state in the target org. Teams that assume sandbox activation carries to production will go live with a broken, invisible agent.
3. Embedded Service deployment must be republished after agent changes — changes to agent instructions, subagents, or actions do not reach users until the Embedded Service deployment is republished. CDN propagation can take up to 10 minutes after republishing.
4. EinsteinServiceAgent User must be selected from the dropdown, never typed — manually typing the user name in the Agent User field fails silently or creates a misconfigured agent that passes validation but cannot execute actions at runtime.
5. An active agent without well-designed subagents is still broken — activating an agent that has only placeholder or template subagents produces an agent that appears live but cannot reliably route or complete tasks. Treat subagent design as a prerequisite to activation, not a post-launch cleanup task.

Output Artifacts

Related Skills

• agentforce/agent-topic-design — use when the problem is subagent boundary design, not agent definition or channel setup.
• agentforce/agent-actions — use when the problem is action contract quality, naming, or error handling within a subagent.
• agentforce/einstein-trust-layer — use alongside this skill to validate data masking, ZDR, and grounding policies before activating an agent.
• devops/scratch-org-management — use when the agent lifecycle includes scratch org-based development or package creation workflows.