# Call functions from your Amazon Bedrock chat agent app
Amazon Bedrock in SageMaker Unified Studio functions let a model include information that it has no previous knowledge of in its response. For example, you can use a function to include dynamic information in a model's response such as a weather forecast, sports results, or traffic conditions.
In Amazon Bedrock in SageMaker Unified Studio, a function calls an API hosted outside of Amazon Bedrock in SageMaker Unified Studio. You either create the API yourself, or use an existing API. To create an API, you can use [ Amazon API Gateway](https://docs.aws.amazon.com/apigateway/).
To use a function in Amazon Bedrock in SageMaker Unified Studio you add a *function component* to your app. As part of the function, you define an OpenAPI schema for the API that you want the model to call. You also specify how to authenticate the call to the API. When a model receives a prompt, it uses the schema and the prompt to determine if an API should be called and the parameters that the API should receive. If the API is called, the response from the model includes the output from the API.
APIs that you call in a function must have a response size that is less than 20K.
When add a function to an app, you need to specify the app's system instruction. The system instruction needs to be at least 40 characters long and should mention the new skills that the new function introduces.
You can use functions in a [chat agent app](create-chat-app.md).
**Topics**
+ [
## Function schema
](#functions-schema)
+ [
## Authentication methods
](#functions-authentication)
+ [
# Create an Amazon Bedrock function component
](creating-a-function-component.md)
+ [
# Add a function component to an Amazon Bedrock chat agent app
](add-function-component-chat-app.md)
## Function schema
Amazon Bedrock in SageMaker Unified Studio has the following requirements for the schema that you use to create a function.
+ The function schema must be [OpenAPI version 3.0.0](https://spec.openapis.org/oas/v3.0.0.html).
+ The function schema must be in JSON or YAML format.
+ The function can have no authentication, API key authentication, Bearer token authentication, or basic authentication. For more information, see [Authentication methods](#functions-authentication).
+ You can have 0 or 1 server URL.
+ All [Operation Objects](https://swagger.io/specification/v3/#operation-object) must have a description.
+ All [Parameter Objects](https://swagger.io/specification/v3/#parameter-object) must have a description.
+ [Security scheme object](https://swagger.io/specification/v3/#security-scheme-object) must have a type that is either `apiKey` or `http`.
When the type is `http`, the scheme field must either be `basic` or `bearer`.
When the type is `apiKey`, the `in` property must be `query` or `header`. Also, the `name` property must be defined.
+ Amazon Bedrock in SageMaker Unified Studio only honors [globally-scoped security requirement](https://swagger.io/specification/v3/#security-requirement-object). For more information, see [Valid components for globally-scoped security requirements](#example-components).
+ Parameters (**parameter.in**) must be pass passed through query or path. You can't use cookies or headers to pass parameters.
+ Parameters (**parameter schema type**) must be primitive types, arrays, or objects (one-level JSON). You can't pass complex nested objects.
+ Parameter content (**parameter.content**) is mutually exclusive with the schema. Schema is more commonly used. Use content only for more complex types, or for complex serialization scenarios that are not covered by style and explode.
+ Parameter **style** and **explode** values. `form` and `true` for query, `simple` and `false` for paths). For more information, see [Parameter Serialization](https://swagger.io/docs/specification/serialization/).
+ Request body content must be passed as `application/json`.
+ The schema can have up to 5 APIs and an app can use up to 5 APIs across all functions. For the model to correctly choose function, it is important to provide detailed descriptions of the API, including parameters, properties, and responses.
### Valid components for globally-scoped security requirements
Amazon Bedrock in SageMaker Unified Studio only honors [globally-scoped security requirements](https://swagger.io/specification/v3/#security-requirement-object). That is, Amazon Bedrock in SageMaker Unified Studio ignores security requirements indicated in operation objects.
When the requirement array contains a security scheme object with type `http` and scheme of `bearer` or `basic`, the array must contain a single entry. Amazon Bedrock in SageMaker Unified Studio ignores further entries.
When the requirement array contains a security scheme object with type `apiKey`, you can have a maximum of 2 entries.
For example, if you have the following [components](https://swagger.io/specification/v3/#components-object):
```
"components": {
"securitySchemes": {
"api_key_1": {
"type": "apiKey",
"name": "appid1",
"in": "query"
},
"api_key_2": {
"type": "apiKey",
"name": "appid2",
"in": "header"
},
"api_key_3": {
"type": "apiKey",
"name": "appid3",
"in": "cookie"
},
"bearer_1": {
"type": "http",
"scheme": "bearer",
},
"bearer_2": {
"type": "http",
"scheme": "bearer",
},
"basic_1": {
"type": "http",
"scheme": "basic",
},
"basic_2": {
"type": "http",
"scheme": "basic",
},
"http_digest": {
"type": "http",
"scheme": "digest"
},
"oauth2_1": {
"type": "oauth2"
}
}
}
```
The following are valid:
```
# 1 API key
"security": [
{
"api_key_1": []
}
],
# 2 API keys
"security": {
{
"api_key_1": [],
"api_key_2": []
}
}
# Bearer
"security": {
"bearer_1": []
}
# Basic
"security": {
"basic_1": []
}
```
The following are invalid:
```
# Invalid: `type` must only be `apiKey` or `http`
"security": {
"oauth2_1": []
}
# Invalid: `scheme` must only be `basic` or `bearer` if `type` is `http`
"security": {
"http_digest": []
}
# Invalid: `security` must only contain 1 entry if `type` is `basic` or `bearer`
"security": {
"basic_1": [],
"basic_2": []
}
# Invalid: `security` must not contain varying security types
"security": {
"api_key_1": [],
"basic_1": []
}
# Invalid: API key must only have `in` property set to `header` or `query`
"security": {
"api_key_1": [],
"api_key_3": []
}
# Invalid: `security` must not have more than 2 API keys
"security": {
{
"api_key_1": [],
"api_key_2": [],
"api_key_3": []
}
}
```
## Authentication methods
Amazon Bedrock in SageMaker Unified Studio supports the following methods for authenticating function calls to an API server. If you authenticate a function call, make sure the credentials you provide are correct as Amazon Bedrock in SageMaker Unified Studio doesn't verify the credentials before you use them in a function call.
+ **No authentication** – No authentication means that the client doesn't need to provide any credentials to access a resource or service. This method is typically used for publicly available resources that don't require any form of authentication.
+ ** [API keys](https://swagger.io/docs/specification/authentication/api-keys/)** – An API key is a unique identifier used to authenticate a client application and allow it to access an API or service. You can add a maximum of two keys.
+ ** [Bearer token](https://swagger.io/docs/specification/authentication/bearer-authentication/)** – A bearer token is an opaque string that represents an authentication credential. It is typically obtained after a successful authentication process, such as OAuth 2.0. This method allows the client to access protected resources without having to send the actual credentials (username and password) with each request.
**Note**
Amazon Bedrock in SageMaker Unified Studio is unable to assure whether the token is valid or has already expired. It is your responsibility to make sure that you provide a valid token, and to update the token to a new one before it expires. If the token expires, Amazon Bedrock won't be able to successfully call APIs with the token.
+ **[Basic authentication](https://swagger.io/docs/specification/authentication/basic-authentication/)** – Basic authentication is a simple authentication scheme built into the HTTP protocol. The credentials are sent with every request, which can be a security concern if the connection is not secured using HTTPS. Basic authentication is generally considered less secure than other modern authentication methods and should be used with caution, especially in production environments.
# Create an Amazon Bedrock function component
You can create a function as a component in an Amazon Bedrock in SageMaker Unified Studio project. If you are creating an app, you can can also create a function when you configure the app.
**To create a function component**
1. Navigate to the Amazon SageMaker Unified Studio landing page by using the URL from your administrator.
1. Access Amazon SageMaker Unified Studio using your IAM or single sign-on (SSO) credentials. For more information, see [Access Amazon SageMaker Unified Studio](getting-started-access-the-portal.md).
1. Choose the **Build** menu at the top of the page.
1. In the **MACHINE LEARNING & GENERATIVE AI** section, choose **My apps**.
1. In the **Select or create a new project to continue** dialog box, select the project that you want to use.
1. In the left pane, choose **Asset gallery**.
1. Choose **My components**.
1. In **Asset gallery**, choose **My components**.
1. In the **Components** section, choose **Create component** and then **Function**. The **Create function** pane is shown.
1. For **Function name**, enter a name for the function in in **Function name**.
1. For **Function description**, enter a description for the function.
1. For **Function schema**, enter the JSON or YAML format OpenAPI schema for the API. Alternatively, upload the JSON or YAML for the file by choosing **Import JSON/YAML**. You can clear the text box by choosing **Reset**.
1. Choose **Validate schema** to validate the schema.
1. For **Authentication method** select the authentication method for your API server. By default, Amazon Bedrock in SageMaker Unified Studio preselects the authentication based on information it finds in your OpenAPI schema. For information about authentication methods, see [Authentication methods](functions.md#functions-authentication).
1. Enter the information for the authention method that you selected in the previous step.
1. For **API servers**, enter the URL for your server in **Server URL**. This value is autopopulated if the server URL is in the schema.
1. Choose **Create** to create your function.
1. Add your function to a chat agent app by doing [Add a function component to an Amazon Bedrock chat agent app](add-function-component-chat-app.md).
# Add a function component to an Amazon Bedrock chat agent app
In this procedure, you add a function component to an existing [chat agent app](create-chat-app.md). You can add up to 5 functions to an app. For each function you add, be sure to update the system instruction with information about the function.
**To add a function component to a chat agent app**
1. Navigate to the Amazon SageMaker Unified Studio landing page by using the URL from your administrator.
1. Access Amazon SageMaker Unified Studio using your IAM or single sign-on (SSO) credentials. For more information, see [Access Amazon SageMaker Unified Studio](getting-started-access-the-portal.md).
1. If the project that you want to use isn't already open, do the following:
1. Choose the current project at the top of the page. If a project isn't already open, choose **Select a project**.
1. Select **Browse all projects**.
1. In **Projects** select the project that you want to use.
1. Choose the **Build** menu option at the top of the page.
1. In **MACHINE LEARNING & GENERATIVE AI** choose **My apps**.
1. In **Apps** choose the chat agent app that you want to add the function component to.
1. In the **Configs** pane, do the following:
1. For **Enter a system instruction**, enter or update the system prompt so that it describes the function.
1. Choose **Functions**.
1. For **Functions**, select the function component that you created in [Create an Amazon Bedrock function component](creating-a-function-component.md).
1. Choose **Save** to save your changes.