---
cuppy_hub: salesforce
cuppy_path: reference/agentforce/agent-script-actions-and-targets.md
cuppy_section: docs
cuppy_doc: GCGG-05VT
cuppy_doc_uuid: 12ec0693-0c7c-4e75-92a3-b08514866ed0
cuppy_permalink: https://cuppy.io/salesforce/d/GCGG-05VT
cuppy_version: 2
cuppy_updated: 2026-10-23T16:16:52.575Z
cuppy_canonical: https://cuppy.io/salesforce/docs/reference/agentforce/agent-script-actions-and-targets
cuppy_mcp: https://cuppy.io/mcp
cuppy_body_sha256: 41253582dac1b8d522e882d645fcda5c0d4583a894dbe761f6af6304082ae63a
# cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks.
---


# Actions and targets

An action is declared once in a subagent's `actions:` block and offered to the LLM as a tool in `reasoning.actions` (`reference/agentforce/agent-script.md`). Agent Script only describes the call. The flow, Apex class or prompt template must already be deployed to the org, because **publishing doesn't deploy them** (`reference/dx/deploy-errors.md`).

## Declaring an action

```agentscript
    actions:
        check_weather:
            description: "Fetch the weather forecast for the resort."
            label: "Check Weather"
            target: "apex://CheckWeather"
            require_user_confirmation: False
            include_in_progress_indicator: True
            progress_indicator_message: "Checking local weather..."
            inputs:
                dateToCheck: object
                    complex_data_type_name: "lightning__dateType"
                    description: "Date to check, yyyy-MM-dd"
                    is_required: True
            outputs:
                maxTemperature: number
                    description: "Maximum temperature in Celsius"
                    is_displayable: True
                    filter_from_agent: False
```

- **`description`s are prompts.** The LLM picks tools and fills inputs from them, so say what the action does and when to use it.
- `is_displayable` lets the output be shown to the user. `filter_from_agent: True` hides an output from the LLM.
- `require_user_confirmation: True` makes the agent ask before running a write action.

## Target schemes

`target: "<scheme>://<API name>"`. The linter accepts:

| Scheme | Calls |
|---|---|
| `flow://` | An autolaunched flow, by API name |
| `apex://` | An Apex class with an `@InvocableMethod` |
| `prompt://` (or `generatePromptResponse://`) | A Prompt Builder template (family 6) |
| `standardInvocableAction://`, `quickAction://` | Built-in invocable actions; quick actions |
| `apexRest://`, `auraEnabled://`, `api://`, `externalService://`, `externalConnector://` | Apex REST methods, `@AuraEnabled` methods, APIs, External Services |
| `mcpTool://`, `platformMcpTool://` | MCP tools (`sf agent mcp` manages the API Catalog) |
| `retriever://` | A Data 360 retriever. Its inputs aren't documented; use a Data Library instead (`reference/data360/search-indexes-and-retrievers.md`) |
| `cdpMlPrediction://` | A Data 360 / Model Builder prediction |
| `namedQuery://`, `expressionSet://`, `runExpressionSet://`, `decisionTableAction://`, `integrationProcedureAction://`, `executeIntegrationProcedure://`, `serviceCatalog://`, `createCatalogItemRequest://`, `slack://` | Industry and platform actions |
| `placeholder://` | A stub for design; the linter warns |

Any other scheme fails, for example: "Action 'verify' uses unsupported target scheme "lambda://". Supported schemes: api, apex, …". The linter doesn't check that the target **exists**. A wrong API name only fails on `sf agent validate`, publish or a live preview.

## Matching names to the implementation

| Target | Input names must match | Outputs |
|---|---|---|
| `apex://Class` | The `@InvocableVariable` fields of the request class | The fields of the response class |
| `flow://Flow` | The flow's input variables (available for input) | Its output variables |
| `prompt://Template` | `"Input:<apiName>"`, **quoted**, one per template input | `promptResponse: string` |

The CLI's agent template pairs this Apex class with the `check_weather` action above:

```apex
public with sharing class CheckWeather {
    @InvocableMethod(label='Check Weather' description='Check weather at the resort for a specific date')
    public static List<WeatherResponse> getWeather(List<WeatherRequest> requests) {
        WeatherResponse response = new WeatherResponse();
        response.maxTemperature = 21.5;
        return new List<WeatherResponse>{ response };
    }
    public class WeatherRequest {
        @InvocableVariable(required=true description='Date to check, yyyy-MM-dd')
        public Date dateToCheck;
    }
    public class WeatherResponse {
        @InvocableVariable(description='Maximum temperature in Celsius')
        public Decimal maxTemperature;
    }
}
```

The same template calls a prompt template with:

```agentscript
            check_events: @actions.check_events
                available when @variables.guest_interests != ""
                with "Input:Event_Type" = @variables.guest_interests
```

## Types and `complex_data_type_name`

- Plain types: `string`, `number`, `boolean`, `date`, `datetime`, `time`, `currency`, `id`, `integer`, `long`, `list[...]`.
- **`object` and `list[object]` need `complex_data_type_name`:**
  - Lightning types: `lightning__dateType`, `lightning__dateTimeType`, `lightning__integerType`, `lightning__doubleType`, `lightning__booleanType`, `lightning__objectType`, `lightning__listType`.
  - An Apex class: `"@apexClassType/c__Outer$Inner"`.
  - Without one, the linter warns: "has type 'object' but lacks 'complex_data_type_name'".
- **On a primitive it's redundant**, and the linter warns: "has primitive type 'string' and does not require 'complex_data_type_name'". Salesforce's own agent template triggers this warning on its prompt template action.
- An Apex `Integer` output generally needs `object` with `lightning__integerType`, per the recipes' rules.

## What publishing creates

`sf agent publish authoring-bundle` compiles the script, creates the agent through the authoring API, then retrieves the generated metadata into your project:

| Org API version | Retrieved |
|---|---|
| 68.0 (Winter '27) and later | `AiAgentDefinition` + `AiAgentDefinitionVersion`, with the action dependencies (flows, Apex, prompt templates) |
| Earlier | `Bot` (+ BotVersion), one `GenAiPlugin` per subagent, one `GenAiFunction` per action, and the `Agent` record |

Commit the generated metadata with the bundle, so a deploy to another org includes the agent's `Bot`/`BotVersion` (`reference/dx/agentforce-metadata-types.md`). The full lifecycle: `guides/agentforce/build-agent-with-agentforce-dx.md`.


---
<!-- cuppy -->
You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 376 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/salesforce/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.
<!-- /cuppy -->