My Org Butler is a showcase for building Agentforce solutions that help Salesforce users with their daily work. It started in early 2024 on the OpenAI Assistants API with a custom LWC frontend, then moved to pure Agentforce when it became powerful enough. Using natural language, it answers questions about data, metadata, and configuration, and can perform tasks like creating records, making configuration changes, or notifying other people.

Find all of Aquiva's My Org Butler related video demos at this YouTube playlist.

1. Install Prerequisite - Install the latest version of the App Foundations package (prerequisite)

2. Install My Org Butler - Grab the latest package version ID from sfdx-project.json and install via Production or Sandbox

3. Enable Agentforce in your org (if not already enabled)

4. Create an Agent from Template - Create a new agent from the My Org Butler template with API name MyOrgButler. See Salesforce Help for instructions.

5. Turn on Optional Features (choose which capabilities you want to enable):

   Turn on Web Search:

   1. Get a free Tavily API key
   2. Go to Setup → Named Credentials → TavilyApi
   3. Click on the linked External Credential TavilyApi
   4. Create a New Named Principal with parameter name ApiKey
   5. Enter your Tavily API key as the value

That's it! The Butler will be available in your Agentforce sidebar.

Built entirely on Agentforce with 1 topic and 14 actions. Agentforce handles AI reasoning and conversation management. The actions handle the Salesforce-specific work:

• Query data, metadata, and settings using natural language SOQL
• Create and update records via the REST API
• Read and modify code and configuration via the Tooling API and Metadata API
• Generate PlantUML diagrams for data models and processes
• Search the web
• Answer questions about a file using platform-native file grounding
• Answer from a Data Library using Data Cloud's DynamicRetriever (requires Data Cloud setup — see below)
• Notify people and delegate tasks to a headless sub-agent

Salesforce Data: ✅ Secure - All queries use USER_MODE and with sharing. Users only see records they have permission to access. Field-level security, object permissions, and sharing rules are fully enforced.

Metadata & Tooling API: ✅ Permission-Gated - Create, update, and delete operations on metadata/code require specific user permissions ("View All Data" for Tooling API, "Modify Metadata" or "Author Apex" for Metadata API). Operations execute with the current user's session - users without these permissions cannot make changes even through the agent.

Slack Integration: ✅ Secure - When used in Slack channels, Agentforce shows you a private draft response first. You review it, then decide whether to share it publicly. This prevents accidental exposure of sensitive data.

The Answer from Data Library action searches company documents using Data Cloud. The scratch org creation script will prompt you to upload a sample PDF into a Data Library — the same file that's already attached to the demo Opportunity for file grounding.

Note: Your DevHub needs "Create Data Cloud Scratch Org" permissions. If you don't have this, open a Partner Community case to request it.

Without completing the Data Library setup, the action deploys fine but returns no results.

1. Clone this repo
2. Replace aquiva_os namespace with your own (or remove it)
3. Create a scratch org: ./scripts/create-scratch-org.sh
4. Make your changes
5. Create a 2GP package in your dev hub (one-time setup)
6. Create package versions: ./scripts/create-package-version.sh

This repo runs an experimental pipeline: a maintainer mentions @butler in an issue or PR, Claude reads the thread, implements the change against a per-PR scratch org, runs the Apex tests, and opens a PR. PR comments mentioning @butler feed back into the same loop until the change ships.

The @butler mention is the only trigger. Opening an issue alone does nothing. The pipeline runs only after a maintainer writes @butler in the body or a comment, on either an issue or a PR. The gate is enforced two ways:

• Open-source DoS protection. The workflow checks author_association on every event and only fires for OWNER, MEMBER, or COLLABORATOR. A random visitor typing @butler in their own issue gets silently ignored — no Anthropic credits burn.
• Closed-source budget control. Even on a private repo, the mention keeps a human in the loop on which tickets are worth spending tokens on. No drive-by ticket auto-fires a run.

Every fire is independent: the agent re-reads the full thread, decides what to do (take it, ask for clarification, propose a split, or refuse), and acts. There are no state labels — to retry after a refusal, just mention @butler again with the override. PRs that the agent opens carry an ai-involved label so humans can filter them at a glance.