Skip to navigation

functions

View as MarkdownOpen in Claude

An array of JSON objects to define functions that can be executed during the interaction with the Amazon Bedrock agent.

Properties

SWAIG.functions
object[]

An array of JSON objects that accept the following properties.

functions[].description
stringRequired

A description of the context and purpose of the function, to explain to the agent when to use it.

functions[].function
stringRequired

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
object

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
object

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
object

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
string

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
string

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

functionstringRequired
The name of the function the agent is calling.
argumentobjectRequired
The arguments the agent passed to your function.
call_idstringRequired
The ID of the call.
ai_session_idstringRequired

The ID of the AI session on the call. Matches call_id for Bedrock agents.

app_namestringRequired

The name of your Bedrock application. Defaults to bedrock.

caller_idstringRequired
The caller's number. An empty string when the call has none.
global_dataobjectRequired

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.

content_typestringRequired

The content type of the request body. Always text/json.

content_dispositionstringRequired

How the body is delivered. Always agent.function for a function call.

conversation_typestringRequired

The kind of conversation the agent is running. Always voice.

actionstringRequired

What the request is asking of you. Always fetch_conversation for a function call; the end-of-call conversation report sends post_conversation instead.

meta_data_tokenstringRequired

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.

meta_dataobjectRequired

Metadata scoped to meta_data_token. An empty object when the function has none yet.

project_idstringOptional
Your project ID, when available.
space_idstringOptional
Your Space ID, when available.
conversation_idstringOptional
The conversation ID, when the agent was configured with one.
caller_id_namestringOptional
The caller's name, when available.
caller_id_numberstringOptional
The caller's number, when available.
call_start_datelongOptional
When the call was created, as a Unix timestamp in microseconds.
call_answer_datelongOptional

When the call was answered, as a Unix timestamp in microseconds. 0 when it never was.

call_end_datelongOptional

When the call ended, as a Unix timestamp in microseconds. 0 while the call is still up.

ai_start_datelongOptional
When the agent started, as a Unix timestamp in microseconds.
ai_end_datelongOptional
When the agent stopped, as a Unix timestamp in microseconds. Omitted while it is still running.
timeslist of objectsOptional

Per-response performance metrics for the session so far. Included once the agent has any.

SWMLVarsobjectOptional
SWML variables for the call. Included when the call carries SWML state.
SWMLCallobjectOptional
SWML call state. Included when the call carries SWML state.

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.

Payload
{
"function": "get_weather",
"argument": {
"parsed": [
{
"city": "San Francisco"
}
],
"raw": "{\"city\":\"San Francisco\"}"
},
"call_id": "2e1e66e5-5d07-413d-9668-55542992eec0",
"ai_session_id": "2e1e66e5-5d07-413d-9668-55542992eec0",
"app_name": "bedrock",
"caller_id": "+15555550100",
"global_data": {
"customer_tier": "premium",
"pickup_address": "123 Main St, Springfield"
},
"content_type": "text/json",
"content_disposition": "agent.function",
"conversation_type": "voice",
"action": "fetch_conversation",
"meta_data_token": "d742c5d1d969d9fdbbd9bd1c52499f2d",
"meta_data": {
"order_number": "12345"
}
}

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
string

The result the agent reads next. When it is absent or not a string, the agent reads Function completed. and carries on.

action
object | object[]

An action, or a list of actions, for the agent to run once it has spoken its reply.

action[].SWML
object | string

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
booleanDefaults to false

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
object

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
object

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
string | string[]

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
string | string[]

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.

{
"response": "It's 82°F and sunny in Tulsa, with 38% humidity and a 2.2 mph wind.",
"action": [
{
"set_meta_data": {
"temperature": 82.0,
"humidity": 38,
"wind_speed": 2.2,
"weather": "Sunny"
}
}
]
}

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
string

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.

Diagram example

Hello, who am I speaking with? You are speaking with the SignalWire assistant. What's the weather in Paris? Call get_weather with location=Paris { "response": "It's sunny and 75°F in Paris." } It's sunny and 75°F in Paris. Intent does NOT match a function Intent matches get_weather function User Bedrock agent Your web_hook_url

SWML Examples

Using SWAIG Functions

version: 1.0.0
sections:
main:
- amazon_bedrock:
post_prompt_url: "https://example.com/my-api"
prompt:
text: |
You are a helpful assistant that can provide information to users about a destination.
At the start of the conversation, always ask the user for their name.
You can use the appropriate function to get weather information.
post_prompt:
text: "Summarize the conversation."
SWAIG:
defaults:
web_hook_url: https://example.com/my-webhook
functions:
- function: get_weather
description: To determine what the current weather is in a provided location.
parameters:
properties:
location:
type: string
description: The name of the city to find the weather from.
type: object
- function: summarize_conversation
description: Summarize the conversation.
parameters:
type: object
properties:
name:
type: string
description: The name of the user.