Apex Class Tools

What is an Apex Class Tool?

An Apex Class tool is the third tool type you can build in the REDA AI Tool Builder, alongside SOQL Template and File Mapping. Reach for it when:

• The work needs conditional logic, multiple steps, or writes to more than one object
• You need to call out to an external system as part of the tool
• You want to reconcile against existing records, deduplicate, or apply business rules before writing
• You’re wiring a file-driven extraction where the structure of the data is too rich for declarative mapping

The platform handles the agent contract: the JSON Schema, input validation, error wrapping, action confirmation, audit logging and result formatting. Your Apex class only owns the work itself.

The Executor Interface

Every Apex Class tool implements a single global interface:

global interface REDAAI_Executable {
    Object execute(String toolName, Map<String, Object> input);
}

Two parameters, one return value:

• toolName — the developer name of the Tool Definition that triggered this call. Use it if a single class implements several tools and needs to switch on the caller.
• input — the parameters the agent provided, validated against your Input Schema JSON, plus the _channel key described below.
• Return value — depends on the tool’s category (see Return contract below).

Knowing which channel you are running in

The same tool can be called by an agent a colleague is chatting with in Salesforce, by a public website widget, or by an unattended API agent running overnight — and it is often right to behave differently in each case. REDA AI therefore adds a set of server-supplied keys to the input map before calling you — starting with the channel:

global class OrderLookupTool implements REDAAI_Executable {
    global Object execute(String toolName, Map<String, Object> input) {
        String channel = (String) input.get('_channel');   // 'Internal' | 'External_Widget' | 'Community' | 'API'

        if (REDAAIConstants.CHANNEL_EXTERNAL_WIDGET.equals(channel)) {
            return summaryForPublicVisitor(input);          // no internal notes, no margins
        }
        return fullInternalDetail(input);
    }
}

The value is one of Internal, External_Widget, Community or API — the same values the Channel field uses, so compare against the REDAAIConstants.CHANNEL_* constants rather than typing the literal. It is set by the platform — not by the agent. If the model tries to supply _channel itself, REDA AI overwrites it; where the channel genuinely cannot be resolved the key is removed altogether rather than left holding a value the model invented. So a present _channel is always trustworthy, and a missing one means “unknown”, never “Internal”.

Two more keys arrive the same way, with the same overwrite-and-remove guarantee — the platform always supplies them, and a value the model tries to set is discarded:

Both are removed rather than left stale when there is no conversation or agent in scope — so, as with _channel, a present value is trustworthy and a missing one means “unknown”.

Existing tools need no change. A tool that never reads _channel simply ignores an extra map entry and behaves exactly as it did before.

Tool Definition Fields

Building the Apex Class

A minimal Action-style executor that creates a single record:

global with sharing class MyToolExecutor implements redaai.REDAAI_Executable {
    global Object execute(String toolName, Map<String, Object> input) {
        try {
            String name = (String) input.get('account_name');
            Account a = new Account(Name = name);
            insert as user a;

            return new Map<String, Object>{
                'success' => true,
                'message' => 'Account created.',
                'recordId' => a.Id
            };
        } catch (Exception e) {
            return new Map<String, Object>{
                'success' => false,
                'message' => e.getMessage()
            };
        }
    }
}

A few things to notice:

• The class is global. Public won’t do — the platform instantiates the class through the global interface so that managed-package consumers can register implementations from their own namespaces.
• The class declares with sharing. The platform doesn’t enforce sharing for you; the executor is responsible for the data-access posture it wants.
• The insert as user clause runs the DML in user mode so field-level security applies. This is the recommended default unless you have a specific reason to escalate.
• Errors are caught and returned as a structured response. Uncaught exceptions are still captured in the incident log, but a clean response gives the agent something useful to say back to the user.

Return Contract

The return shape depends on the tool’s Category:

File-Driven Apex Tools

Setting Is File Processing to true changes what the agent passes you. Instead of free-form parameters, the platform first asks the model to extract structured data from the uploaded file using the schema you defined, then hands that extracted data to your executor as the input Map.

That is what makes Apex Class tools the right pattern for non-tabular file work — PDFs, images, mixed documents — where File Mapping’s flat column-to-field model isn’t enough.

Designing the input schema for extraction

The input schema describes the extracted shape, not the raw file. For a multi-row document the agent might produce something like:

{
  "rows": [
    { "external_id": "INV-1001", "amount": 250.00, "due_date": "2026-05-01" },
    { "external_id": "INV-1002", "amount": 980.50, "due_date": "2026-05-15" }
  ]
}

Your executor then iterates that rows array, looks up matching records, applies whatever business rules you need, and writes back to Salesforce.

When you build the tool in the Tool Builder with Is File Processing turned on, the AI Generator can produce a sample of the extracted data shape from a representative file you upload. Use it as the contract you write your Apex against.

Naming, Packaging & Resolution

• Class visibility — the class and its execute method must both be declared global (not public).
• Implementation — must implement redaai.REDAAI_Executable.
• Class name length — up to 255 characters in the Executor Class field.
• One class, multiple tools — a single executor can back several Tool Definitions and switch behaviour on toolName.

Security & Governance

• You own the security posture. The platform doesn’t enforce FLS or sharing inside your class. Use with sharing and the USER_MODE / as user patterns unless you have an explicit reason to escalate.
• Security acknowledgment on save. The first time you save a custom tool (Apex, SOQL Template or File Mapping) in the Tool Builder, you accept a shared-responsibility acknowledgment confirming you are responsible for its security, permissions (CRUD/FLS), data scoping, input validation and legal compliance — because REDA AI may invoke it autonomously, including on Community and External channels without a human confirmation step. Your acceptance (name + timestamp) is recorded on the tool and supplements the REDA AI Master Service Agreement. Built-in (ISV) tools are exempt; you accept once per tool and it’s preserved across edits.
• Input is validated. The platform validates input against your schema before invoking your class — you can trust the field names and types you declared, but always defensively cast values.
• Action confirmation still applies. Setting Category to Action means the agent shows a confirmation card before calling your class, unless the agent is configured for auto-execution.
• Errors land in incidents. Uncaught exceptions are captured as REDA AI incident records with the conversation, tool name and stack context. Returning a clean error response is friendlier; the incident log is the safety net.
• Synchronous execution. Apex Class tools run inline as part of the agent’s turn. Long-running work should be queued by your executor (Queueable, Schedulable, batch) and the immediate response should tell the user the work has been started.

When to Reach For an Apex Tool

Best Practices

Make the description ruthless. The agent’s decision to call your tool depends almost entirely on the tool description. Spell out what the tool does, what it does not do, and any preconditions.

Keep schemas tight. Use required, enum, maxLength and explicit types. The tighter the schema, the fewer surprises hit your Apex.

Always return a useful message. Even on failure, return success: false and a human-readable message. The agent reads the message back to the user; opaque errors lead to confused conversations.

Stay synchronous, or queue and report. Don’t block the agent turn on a slow callout. Either complete fast, or enqueue async work and return a response that tells the user it’s in progress.

Test with the Tool Builder preview panel. The live impact panel shows the input schema, action card and runtime contract the agent will see — catch mismatches there before the first real conversation.

Frequently Asked Questions

Next Steps

Read SOQL Template Tools for the lighter-weight pattern when all you need is a parameterised query, or Document Processing for the bigger picture of how files flow through REDA AI.