Return

Overview

The Return expression signals the end of a compound action’s execution, streaming mapped data back to the chat for user-layer runs. In system-layer runs, it will stop quietly, and any returned data is sent to the caller. The expression also works as an early-return expression, you can place it at the end of the flow or in a Switch case to simplify logic.

Unlike an error-based exit (handled by a raise expression), the return expression exits gracefully, providing a way to output data in a structured format using the output_mapper, which follows the Moveworks Data Mapping Syntax.

Different behaviors based on content

Context	What Happens	Best For
User-Layer	Returns data and the assistant provides it to the user	Deliver results to users
System-Layer	Returns data and it is provided to	Backend orchestration

️ Keep these in mind

Be mindful of our token limits.
Return statements have some reserved keywords for Citations (results & result). Please do not use the keyword “result” unless you plan to include an “id” and “friendly_id” (optional) which will create a citation.

Low-Code Editor

Add the Return step and map the data to be returned.

Map the Data: Build the output mapper with keys and DSL, pull from the data bank and transform on the fly.

Leave Early: Stop execution early when condition is triggered in switch cases

Syntax Reference

Schema

1 return:
2   output_mapper:  # Optional dict for structured chat output (user context only)
3     key1: DSL_MAPPED_VALUE  # e.g., "summary: data.results | $JOIN(', ')"
4     key2: DSL_MAPPED_VALUE  # Supports transforms like MAP(), $TITLECASE()
5     # Reserved: Avoid "result" unless for citations (needs "id"/"friendly_id")

Fields

Field	Type	Mandatory	Description
`output_mapper`	dict	No	Transforms and maps data bank variables

Practical Examples

Example 1: Basic Action Handoff

Return the aggregated result of two actions

Compound action

1 steps: 
2   - action:
3       action_name: fetch_data_one
4       output_key: action_output_one  # e.g., { "status": "success", "data": { ... } }
5   - action:
6       action_name: fetch_data_two
7       output_key: action_output_two  # e.g., { "priority": "2" }
8   - return:
9       output_mapper:
10         output_one: data.action_output_one
11         output_two: data.action_output_two

Result Expectation

1 {
2   "output_one": {
3     "status": "success",
4     "data": {
5       "value": 42,
6       "description": "The answer to life, the universe, and everything."
7     }
8   },
9   "output_two": {
10     "priority": "2"
11   }
12 }

Example 2: Filtered User List

Transform a list of users

Compound action

1 steps: 
2   - action:
3       action_name: fetch_users
4       output_key: users_output
5   - return:
6       output_mapper:
7         user_list: 
8           MAP():
9             items: data.users_output
10             converter:
11               id: item.id
12               display_name: item.name.$TITLECASE()

Data bank

1 {
2   "data": {
3     "users_output": [
4       { "id": "user1", "name": "alice", "age": 30 },
5       { "id": "user2", "name": "bob", "age": 25 },
6       { "id": "user3", "name": "charlie", "age": 35 }
7     ]
8   }
9 }

Result Expectation

1 {
2   "user_list": [
3     {
4       "id": 1,
5       "display_name": "Alice"
6     },
7     {
8       "id": 2,
9       "display_name": "Bob"
10     },
11     {
12       "id": 3,
13       "display_name": "Charlie"
14     }
15   ]
16 }

Example 3: Early return in Switch

Skip approval process if user is admin

1 steps: 
2   - switch:
3       cases:
4         - condition: meta_info.user.role == "admin"
5           steps:
6             - action:
7                 action_name: grant_access_to_grafana
8                 output_key: admin_grafana_access_output
9             - return: # Early exit here
10                 output_mapper: {}
11       default:
12         - steps:
13             - action:
14                 output_key: create_generic_approval_request_result
15                 action_name: mw.create_generic_approval_request
16                 input_args:
17                   approval_key: '"MANAGER"'
18                   approval_details: '"Need access to Grafana"'
19                   users_requested_for: meta_info.user
20   - action:
21       action_name: do_another_action
22       output_key: another_action_output
23   - action:
24       action_name: do_another_action_two
25       output_key: another_action_output_two

1	return:
2	output_mapper: # Optional dict for structured chat output (user context only)
3	key1: DSL_MAPPED_VALUE # e.g., "summary: data.results \| $JOIN(', ')"
4	key2: DSL_MAPPED_VALUE # Supports transforms like MAP(), $TITLECASE()
5	# Reserved: Avoid "result" unless for citations (needs "id"/"friendly_id")

1	steps:
2	- action:
3	action_name: fetch_data_one
4	output_key: action_output_one # e.g., { "status": "success", "data": { ... } }
5	- action:
6	action_name: fetch_data_two
7	output_key: action_output_two # e.g., { "priority": "2" }
8	- return:
9	output_mapper:
10	output_one: data.action_output_one
11	output_two: data.action_output_two

1	{
2	"output_one": {
3	"status": "success",
4	"data": {
5	"value": 42,
6	"description": "The answer to life, the universe, and everything."
7	}
8	},
9	"output_two": {
10	"priority": "2"
11	}
12	}

1	steps:
2	- action:
3	action_name: fetch_users
4	output_key: users_output
5	- return:
6	output_mapper:
7	user_list:
8	MAP():
9	items: data.users_output
10	converter:
11	id: item.id
12	display_name: item.name.$TITLECASE()

1	{
2	"data": {
3	"users_output": [
4	{ "id": "user1", "name": "alice", "age": 30 },
5	{ "id": "user2", "name": "bob", "age": 25 },
6	{ "id": "user3", "name": "charlie", "age": 35 }
7	]
8	}
9	}

1	{
2	"user_list": [
3	{
4	"id": 1,
5	"display_name": "Alice"
6	},
7	{
8	"id": 2,
9	"display_name": "Bob"
10	},
11	{
12	"id": 3,
13	"display_name": "Charlie"
14	}
15	]
16	}

1	steps:
2	- switch:
3	cases:
4	- condition: meta_info.user.role == "admin"
5	steps:
6	- action:
7	action_name: grant_access_to_grafana
8	output_key: admin_grafana_access_output
9	- return: # Early exit here
10	output_mapper: {}
11	default:
12	- steps:
13	- action:
14	output_key: create_generic_approval_request_result
15	action_name: mw.create_generic_approval_request
16	input_args:
17	approval_key: '"MANAGER"'
18	approval_details: '"Need access to Grafana"'
19	users_requested_for: meta_info.user
20	- action:
21	action_name: do_another_action
22	output_key: another_action_output
23	- action:
24	action_name: do_another_action_two
25	output_key: another_action_output_two