> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes. # functions > Functions that can be executed during the interaction with the Amazon Bedrock agent. [reserved-functions]: #reserved-functions [post-prompt]: /docs/swml/reference/calling/amazon-bedrock#post_prompt-properties 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`** `string` — required A description of the context and purpose of the function, to explain to the agent when to use it. --- **`functions[].function`** `string` — required A unique name for the function. This can be any user-defined string or can reference a reserved function. Reserved functoins are SignalWire functions that will be executed at certain points in the conversation. To learn more about reserved functions, see [Reserved Functions][reserved-functions]. --- **`functions[].active`** `boolean` — default: true Whether the function is active. --- **`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`](/docs/swml/reference/calling/amazon-bedrock/swaig/functions/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`](/docs/swml/reference/calling/amazon-bedrock/swaig/functions/parameters) for additional details. --- **`functions[].meta_data`** `object` A powerful and flexible environmental variable which can accept arbitrary data that is set initially in the SWML script or from the SWML [`set_meta_data` action](/docs/swml/reference/calling/amazon-bedrock/swaig/functions/data-map#actions). This data can be referenced **locally** to the function. All contained information can be accessed and expanded within the prompt - for example, by using a template string. --- **`functions[].meta_data_token`** `string` — default: Set by SignalWire Scoping token for `meta_data`. If not supplied, metadata will be scoped to function's `web_hook_url`. --- **`functions[].web_hook_url`** `string` Function-specific URL to send status callbacks and reports to. Takes precedence over a default setting. 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. ### Request ### Schema (`Webhooks.AI.BedrockSwaigToolWebhookPayload`) ```yaml components: schemas: WebhooksAiBedrockSwaigToolWebhookPayloadArgumentParsedItems: type: object properties: {} title: WebhooksAiBedrockSwaigToolWebhookPayloadArgumentParsedItems WebhooksAiBedrockSwaigToolWebhookPayloadArgument: type: object properties: parsed: type: array items: $ref: >- #/components/schemas/WebhooksAiBedrockSwaigToolWebhookPayloadArgumentParsedItems description: The arguments parsed into objects. Usually a single-element array. raw: type: string description: The raw argument string, exactly as the agent produced it. required: - parsed - raw description: The arguments the agent passed to your function. title: WebhooksAiBedrockSwaigToolWebhookPayloadArgument WebhooksAiBedrockSwaigToolWebhookPayloadGlobalData: type: object properties: {} description: >- 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. title: WebhooksAiBedrockSwaigToolWebhookPayloadGlobalData Webhooks.AI.AIResponseTiming: type: object properties: response: type: string description: The reply text. Redacted when you enable `redact_prompt`. response_word_count: type: integer description: How many words the reply contained. answer_time: type: number format: double description: How long the reply took to produce, in seconds. token_time: type: number format: double description: >- How long the model spent generating, in seconds. For an [`ai`](/docs/swml/reference/calling/ai) agent this is the span from the first token to the last; for an [`amazon_bedrock`](/docs/swml/reference/calling/amazon-bedrock) agent it is `answer_time` less a fixed startup estimate, so treat it as approximate there. tokens: type: integer description: How many tokens the reply used. avg_tps: type: number format: double description: Average tokens per second across the reply. tps: type: number format: double description: Tokens per second for this reply. required: - response - response_word_count - answer_time - token_time - tokens - avg_tps - tps description: Timing and token counts for one generated reply. title: Webhooks.AI.AIResponseTiming WebhooksAiBedrockSwaigToolWebhookPayloadSwmlVars: type: object properties: {} description: SWML variables for the call. Included when the call carries SWML state. title: WebhooksAiBedrockSwaigToolWebhookPayloadSwmlVars WebhooksAiBedrockSwaigToolWebhookPayloadSwmlCall: type: object properties: {} description: SWML call state. Included when the call carries SWML state. title: WebhooksAiBedrockSwaigToolWebhookPayloadSwmlCall WebhooksAiBedrockSwaigToolWebhookPayloadMetaData: type: object properties: {} description: >- Metadata scoped to `meta_data_token`. An empty object when the function has none yet. title: WebhooksAiBedrockSwaigToolWebhookPayloadMetaData Webhooks.AI.BedrockSwaigToolWebhookPayload: type: object properties: function: type: string description: The name of the function the agent is calling. argument: $ref: >- #/components/schemas/WebhooksAiBedrockSwaigToolWebhookPayloadArgument description: The arguments the agent passed to your function. call_id: type: string description: The ID of the call. ai_session_id: type: string description: >- The ID of the AI session on the call. Matches `call_id` for Bedrock agents. app_name: type: string description: The name of your Bedrock application. Defaults to `bedrock`. caller_id: type: string description: The caller's number. An empty string when the call has none. global_data: $ref: >- #/components/schemas/WebhooksAiBedrockSwaigToolWebhookPayloadGlobalData description: >- 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_type: type: string description: The content type of the request body. Always `text/json`. content_disposition: type: string description: >- How the body is delivered. Always `agent.function` for a function call. conversation_type: type: string description: The kind of conversation the agent is running. Always `voice`. action: type: string description: >- What the request is asking of you. Always `fetch_conversation` for a function call; the end-of-call conversation report sends `post_conversation` instead. project_id: type: string description: Your project ID, when available. space_id: type: string description: Your Space ID, when available. conversation_id: type: string description: The conversation ID, when the agent was configured with one. caller_id_name: type: string description: The caller's name, when available. caller_id_number: type: string description: The caller's number, when available. call_start_date: type: integer format: int64 description: When the call was created, as a Unix timestamp in microseconds. call_answer_date: type: integer format: int64 description: >- When the call was answered, as a Unix timestamp in microseconds. `0` when it never was. call_end_date: type: integer format: int64 description: >- When the call ended, as a Unix timestamp in microseconds. `0` while the call is still up. ai_start_date: type: integer format: int64 description: When the agent started, as a Unix timestamp in microseconds. ai_end_date: type: integer format: int64 description: >- When the agent stopped, as a Unix timestamp in microseconds. Omitted while it is still running. times: type: array items: $ref: '#/components/schemas/Webhooks.AI.AIResponseTiming' description: >- Per-response performance metrics for the session so far. Included once the agent has any. SWMLVars: $ref: >- #/components/schemas/WebhooksAiBedrockSwaigToolWebhookPayloadSwmlVars description: >- SWML variables for the call. Included when the call carries SWML state. SWMLCall: $ref: >- #/components/schemas/WebhooksAiBedrockSwaigToolWebhookPayloadSwmlCall description: SWML call state. Included when the call carries SWML state. meta_data_token: type: string description: >- 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_data: $ref: >- #/components/schemas/WebhooksAiBedrockSwaigToolWebhookPayloadMetaData description: >- Metadata scoped to `meta_data_token`. An empty object when the function has none yet. required: - function - argument - call_id - ai_session_id - app_name - caller_id - global_data - content_type - content_disposition - conversation_type - action - meta_data_token - meta_data title: Webhooks.AI.BedrockSwaigToolWebhookPayload ``` > **Note** > > This payload differs from the one an [`ai`](/docs/swml/reference/calling/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](/docs/apis/rest/webhooks/bedrock-swaig-tool-webhook) webhook page for the full field reference. ### Reply Return a JSON object with a `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` — required Static text that will be added to the AI agent's context. --- **`action`** `object[]` A list of SWML-compatible objects that are executed upon the execution of a SWAIG function. --- [set\_meta\_data]: /docs/swml/guides/set-meta-data[properties]: /docs/swml/reference/calling/amazon-bedrock#properties **`action[].SWML`** `object | string` A SWML object to be executed. 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`** `boolean` 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 this boolean form. The object form that transfers to a named destination is specific to [`ai`](/docs/swml/reference/calling/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`][properties] 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`][properties] to be referenced locally in the function. See [`set_meta_data`][set_meta_data] for additional details. --- **`action[].unset_global_data`** `string | string[]` The key of the global data to unset from the [`global_data`][properties], 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`][properties], or an array of keys to unset several at once. --- > **Note** > > Bedrock agents accept a smaller set of actions than [`ai`](/docs/swml/reference/calling/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. ```json { "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 Functions** Reserved functions are special SignalWire functions that are automatically triggered at specific points during a conversation. You define them just like any other SWAIG function, but their names correspond to built-in logic on the SignalWire platform, allowing them to perform specific actions at the appropriate time. > **Function name conflicts** > > Do not use reserved function names for your own SWAIG functions unless you want to use the reserved function's built-in behavior. > Otherwise, your function may not work as expected. ### List of Reserved Functions **`start_hook`** `string` Triggered when the call is answered. Sends the set properties of the function to the defined `web_hook_url`. --- **`stop_hook`** `string` Triggered when the call is ended. Sends the set properties of the function to the defined `web_hook_url`. --- **`summarize_conversation`** `string` Triggered when the call is ended. The [`post_prompt`][post-prompt] must be defined for this function to be triggered. Provides a summary of the conversation and any set properties to the defined `web_hook_url`. --- > **Where are my function properties?** > > If the AI is not returning the properties you set in your SWAIG function, it may be because a reserved function was triggered before > those properties were available. To ensure your function receives all necessary information, make sure the AI has access to the > required property values before the reserved function is called. Any property missing at the time the reserved function runs will > not be included in the data sent back. ## Diagram examples ```mermaid sequenceDiagram participant SW System participant User participant AI participant SWAIG %% Call starts SW System->>AI: Event: Call answered AI->>SWAIG: Trigger reserved function start_hook SWAIG->>AI: start_hook response %% User asks a simple question (no function needed) User->>AI: "Hello, who am I speaking with?" Note right of AI: Intent does NOT match a function AI->>User: "You are speaking with the SignalWire assistant." %% User asks for weather (triggers function) User->>AI: "What's the weather in Paris?" Note right of AI: Intent matches get_weather function AI->>SWAIG: Call get_weather with location=Paris SWAIG->>AI: Response payload:
{ "location": "Paris", "temp": "75°F", "condition": "Sunny" } AI->>User: "It's sunny and 75°F in Paris." %% Call ends SW System->>AI: Event: Call ended AI->>SWAIG: Trigger reserved function stop_hook SWAIG->>AI: stop_hook response %% Conversation ends (post_prompt defined) SW System->>AI: Event: Conversation ended AI->>SWAIG: Trigger reserved function summarize_conversation ``` ## SWML **Examples** ### Using SWAIG Functions #### YAML ```yaml 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. ``` #### JSON ```json { "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.\nAt the start of the conversation, always ask the user for their name.\nYou can use the appropriate function to get weather information.\n" }, "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." } } } } ] } } } ] } } ``` > Functions that can be executed during the interaction with the Amazon Bedrock agent. ## Docs - [data_map](https://signalwire.com/docs/swml/reference/calling/amazon-bedrock/swaig/functions/data-map.md): Defines how a SWAIG function should process and respond to the user's input data. - [parameters](https://signalwire.com/docs/swml/reference/calling/amazon-bedrock/swaig/functions/parameters.md): The parameters object for the SWAIG function.