With the shift toward Agentforce, I’m trying to build a custom action that allows the AI to fetch real-time shipping status from an external ERP. I’ve written the Apex class with @InvocableMethod, but the agent isn't always recognizing the input parameters correctly. How do I structure the metadata and descriptions so the LLM understands exactly when and how to call my Apex action?
3 answers
The "Description" attribute in your @InvocableMethod and @InvocableVariable is the most important part of Agentforce development. The LLM uses these strings as instructions to decide if the action matches the user's intent. You need to be extremely descriptive—instead of "Fetch Status," use "Retrieves the current shipping status and estimated delivery date from the external ERP using a 10-digit Tracking ID." Also, ensure your output is a class containing primitive types or a list of classes, as the Agent handles structured data better than raw JSON strings.
Are you handling the authentication within the Apex class using Named Credentials? If the Agent tries to call your action and hits a 401 Unauthorized error because the session isn't properly established, it might hallucinate a generic "I can't find that info" response. Is your service principal properly mapped to the Agentforce execution context?
Make sure your @InvocableMethod is set to 'callout=true' in the annotation. If you don't, the action will fail immediately when trying to reach the ERP endpoint.
Good catch, Mary. That 'callout=true' flag is the most common reason for those cryptic "Internal Server Error" messages in the Einstein Copilot debugger.
James, I was using hardcoded headers for testing—bad move! I switched to Named Credentials with External Credentials for OAuth 2.0. Now the Agent handles the handshake perfectly. Barbara’s tip about descriptions was also a lifesaver; once I added specific "input requirements" to the description, the Agent stopped trying to pass the Order Name into the Tracking ID field.