functions
An array of JSON objects to define functions that can be executed during the interaction with the Amazon Bedrock agent.
Properties
SWAIG.functions
An array of JSON objects that accept the following properties.
functions[].description
A description of the context and purpose of the function, to explain to the agent when to use it.
functions[].function
A unique name for the function. The agent calls the function by this name. The name summarize_conversation is
reserved for the end-of-call summary; see Reserved function names.
functions[].data_map
An object containing properties to process or validate the input, perform actions based on the input, or connect to external APIs or services in a serverless fashion.
See data_map for additional details.
functions[].parameters
A JSON object that defines the expected user input parameters and their validation rules for the function.
See parameters for additional details.
functions[].meta_data
Data for this function. It is sent with each call to the function’s web_hook_url and is available to its
data_map templates under
session_data.meta_data. Functions that share a meta_data_token share one set of metadata.
functions[].meta_data_token
Scoping token for meta_data. Functions that set the same token share their metadata. When omitted, the metadata is
scoped to this function’s name, so it is not shared with other functions.
functions[].web_hook_url
Function-specific URL that receives calls to this function. Takes precedence over defaults.web_hook_url. Authentication can also be set in the url in the format of username:password@url.
Tool webhook
When the agent calls one of your SWAIG functions, the platform sends an HTTP POST to that function’s
web_hook_url (or the SWAIG defaults.web_hook_url). Your endpoint runs the function and returns a JSON
object with a response string (the result the agent reads next) and, optionally, an action — a single
object or an array — telling the agent what to do once it has spoken its reply.
Request
The ID of the AI session on the call. Matches call_id for Bedrock agents.
The name of your Bedrock application. Defaults to bedrock.
The agent's current global_data. Alongside anything you seeded, the session adds
caller_id_name and caller_id_number when the call carries them.
The content type of the request body. Always text/json.
How the body is delivered. Always agent.function for a function call.
The kind of conversation the agent is running. Always voice.
What the request is asking of you. Always fetch_conversation for a function call; the
end-of-call conversation report sends post_conversation instead.
The token that scopes meta_data. This is the meta_data_token you set on the function, or an
MD5 of the function's name when you did not set one.
Metadata scoped to meta_data_token. An empty object when the function has none yet.
When the call was answered, as a Unix timestamp in microseconds. 0 when it never was.
When the call ended, as a Unix timestamp in microseconds. 0 while the call is still up.
Per-response performance metrics for the session so far. Included once the agent has any.
This payload differs from the one an ai agent sends. content_type
is text/json rather than text/swaig, argument carries no substituted value, and there is no
version, description, or argument_desc. The caller’s number arrives as caller_id (and as
caller_id_number when the call has a caller profile) rather than caller_id_num.
Write your handler against this list, not the ai one.
See the Amazon Bedrock SWAIG tool webhook webhook page for the full field reference.
Reply
Return a JSON object with an optional response key and an optional action key. The response is the
text the agent reads next, and action carries SWML-compatible objects that change what the call does next.
response
The result the agent reads next. When it is absent or not a string, the agent reads Function completed. and
carries on.
action
An action, or a list of actions, for the agent to run once it has spoken its reply.
action[].SWML
A SWML document to run, as an object or as a JSON string. By default it runs inline and the agent resumes the conversation
afterward. Pair it with a sibling action[].transfer set to true to hand the call off to that
SWML instead and end the agent.
action[].transfer
Use alongside a sibling action[].SWML payload in the same action object. When true, ends the
agent and hard-transfers the call to that SWML. When omitted or false, the SWML executes inline
and the agent continues afterward.
Bedrock agents accept only true or false here; in a data_map output, a variable that expands
to one of them also works. The object form that transfers to a named destination is specific to
ai agents.
action[].set_global_data
A JSON object containing any global data, as a key-value map. This action sets the data in the
global_data to be globally referenced.
action[].set_meta_data
A JSON object containing any metadata, as a key-value map. This action sets the data in the
meta_data to be referenced locally in the function.
See set_meta_data for additional details.
action[].unset_global_data
The key of the global data to unset from the global_data, or an array of keys to
unset several at once.
action[].unset_meta_data
The key of the metadata to unset from the meta_data, or an array of keys to unset
several at once.
Bedrock agents accept a smaller set of actions than ai agents.
The six above are the whole list: there is no say, stop, hangup, hold, toggle_functions,
context_switch, change_context, change_step, user_input, playback_bg, or stop_playback_bg.
An unrecognized key in action is ignored rather than reported as an error, so a payload written for
an ai agent fails quietly here.
Reserved function names
A Bedrock agent runs none of your functions automatically: every function you define is offered to the agent, which
calls it when the conversation needs it. The one reserved name is summarize_conversation.
summarize_conversation
Reserved for the summary written when the conversation ends. A function with this name is not offered to the agent
during the call. The summary is written only when post_prompt_url is set, and is sent to that
URL. post_prompt supplies the summary instructions; when it is omitted, a default instruction is
used.