> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.elacity.ai/llms.txt.
> For full documentation content, see https://docs.elacity.ai/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.elacity.ai/_mcp/server.

# AWS Bedrock AI Agent

The AWS Bedrock deploy provider allows you to push versioned prompts and tools from Elacity directly into **AWS Bedrock Agents**. This integration automates the creation of agents, synchronization of Action Groups (tools), and handles the technical "Preparation" step required by Bedrock.

## AWS Environment Setup (Step-by-Step)

Follow these steps to prepare your AWS account for integration with Elacity.

### 1. Create an IAM User

Elacity needs programmatic access to your AWS account to manage agents.

1. Log in to your **AWS IAM Console**.
2. Create a new user with a name like `elacity-deployer`.
3. Select **Attach policies directly** and add:
   * `AmazonBedrockFullAccess`
   * `AWSLambda_FullAccess` (required for tool execution)
4. **Critical Step: Add `iam:PassRole` permission.**
   Without this, you will get an `AccessDeniedException` during deployment. Create an **Inline Policy** for the user with the following JSON:
   ```json
   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "iam:PassRole",
               "Resource": "*" 
           }
       ]
   }
   ```
   *(Note: You can replace `*` with the specific ARN of your Bedrock Service Role for better security).*

### 2. Configure a Service Role for Bedrock

Bedrock Agents require a dedicated service role to interact with foundation models.

1. In the IAM Console, create a new **Role**.
2. Select **AWS Service** and then **Bedrock**.
3. Attach policies that grant access to the models you plan to use (e.g., Amazon Nova/Titan).
4. **Important:** Copy the **Role ARN** (e.g., `arn:aws:iam::123456789012:role/BedrockAgentServiceRole`). You will need this in Elacity.

### 3. Request Model Access

Navigate to the **Bedrock Console** in your target region and ensure you have "Granted" access to your chosen models (e.g., Amazon Nova/Titan, Meta Llama) under **Model Access**.

***

## Connection Setup in Elacity

### 1. Secret Configuration

In Elacity, navigate to **Environments / Secrets** and add your AWS credentials.

> \[!WARNING]
> **Authentication Types:**
>
> * **IAM User (Permanent Keys):** Use `AWS_ACCESS_KEY_ID` (starts with `AKIA`) and `AWS_SECRET_ACCESS_KEY`. Leave `AWS_SESSION_TOKEN` **empty**.
> * **SSO / Temporary Credentials:** Use `AWS_ACCESS_KEY_ID` (starts with `ASIA`), `AWS_SECRET_ACCESS_KEY`, and you **MUST** provide the `AWS_SESSION_TOKEN`.

| Secret Name                 | Value                                                    |
| :-------------------------- | :------------------------------------------------------- |
| **`AWS_ACCESS_KEY_ID`**     | Your Access Key                                          |
| **`AWS_SECRET_ACCESS_KEY`** | Your Secret Key                                          |
| **`AWS_REGION`**            | e.g., `us-east-1`                                        |
| **`AWS_SESSION_TOKEN`**     | Only for `ASIA...` keys. Leave empty for `AKIA...` keys. |

### 2. Agent Configuration

When creating or updating an agent in Elacity, use the following provider-specific fields:

* **Agent Name**: The display name in the AWS console.
* **Foundation Model**: The exact model ID (e.g., `amazon.nova-pro-v1:0`).
* **Agent Resource Role ARN**: The ARN of the service role created in Step 2.
* **Instruction**: Your system prompt.
  > \[!IMPORTANT]
  > **Length Requirement:** Bedrock agents require a substantial instruction. Elacity enforces a minimum of **40 characters** for the cleaned instruction.

***

## Working with Tools (Action Groups)

AWS Bedrock uses **Action Groups** to represent tools. Elacity supports two main tool workflows:

### Built-in AWS Tools

If you select a tool type like **User Input**, Elacity automatically configures it as a built-in Bedrock tool.

* **System Name:** `AMAZON.UserInput`
* **Config:** No Lambda or Schema required.

### Custom Lambda Actions

For specialized logic, use the **Lambda Action** tool type.

1. Create a Lambda function in AWS.
2. Grant Bedrock permission to invoke it:
   ```bash
   aws lambda add-permission --function-name YourFunctionName --principal bedrock.amazonaws.com --action lambda:InvokeFunction --statement-id AllowBedrock
   ```
3. Copy the **Lambda ARN** into the `actionGroupExecutor` field in the Elacity tool editor.
4. **Schema:** Provide either an **API Schema** (OpenAPI) or a **Function Schema**.

> \[!IMPORTANT]
> **Conflict Rule:** Do not provide both `apiSchema` and `functionSchema` in the same tool. Elacity will prioritize `apiSchema` if both are present.

***

## Troubleshooting & Typical Errors

### Access Denied (iam:PassRole)

**Error:** `User ... is not authorized to perform: iam:PassRole`

* **Fix:** Add the `iam:PassRole` inline policy to your IAM User as described in Step 1. Ensure the `Resource` includes the ARN of the Role you are trying to use.

### Bad control character in JSON (position 190)

**Error:** `Bad control character in string literal in JSON`

* **Fix:** This is usually a secondary error caused by an underlying 403 Forbidden or 401 Unauthorized response from AWS. Check your credentials and ensure the region is correct. Also, ensure you are not passing an empty/stale `AWS_SESSION_TOKEN` if using permanent `AKIA` keys.

### Invalid Security Token

**Error:** `The security token included in the request is invalid`

* **Fix:** Clear the `AWS_SESSION_TOKEN` secret. It is almost always the cause when using permanent IAM keys.

### Invalid Name Pattern

**Error:** `Member must satisfy regular expression pattern: ([0-9a-zA-Z][_-]?){1,100}`

* **Fix:** Remove dots (`.`) and spaces from your Tool/Action Group names. AWS only allows alphanumeric characters, underscores, and hyphens.

### Missing Lambda Permissions

**Error:** `The agent doesn't have permission to invoke the Lambda function...`

* **Fix:** Ensure you've run the `aws lambda add-permission` command mentioned in the Tools section above.

### Schema Validation Fails

**Error:** `Failed to create OpenAPI 3 model...`

* **Fix:** Your `apiSchema.payload` must be a valid JSON/YAML OpenAPI specification. If you want a simpler setup, delete `apiSchema` and use `functionSchema` instead.

***

## Deployment Verification

1. Click **Deploy** in Elacity.
2. Navigate to the **AWS Bedrock Console > Agents**.
3. Select your agent and verify the **Action Groups** are synced and the status is **Prepared**.