> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS Bedrock Agents Setup

> Connect a Bedrock Agent built in AWS to an Elementum App via App Intelligence, and invoke it from automations

## Overview

AWS Bedrock Agents are agents you build in your own AWS account using Amazon foundation models, knowledge bases, action groups, and guardrails. Elementum lets you connect a Bedrock Agent to an App through **App Intelligence** so you can invoke it from automations and conversational workflows—while data access and execution stay inside your AWS environment.

You will:

* (If needed) Create a Bedrock Agent and an agent alias in AWS.
* Add `bedrock:InvokeAgent` to the IAM user used by your Bedrock AI Provider.
* Connect the agent to an App through App Intelligence using the **Agent Alias ARN**.
* Use the agent in automations via **Run Agent Task**.

<Info>
  **Time required**: About 15–30 minutes if your Bedrock Agent already exists in AWS; longer if you are building the agent from scratch.
</Info>

## Prerequisites

### Elementum requirements

* **App access**: Access to the App where you want to use the Bedrock Agent.
* **Bedrock AI Provider configured**: An Amazon Bedrock AI Provider must already exist in **Organization Settings → Providers**. If you haven't set this up, complete [AWS Bedrock Setup](/ai-agents/bedrock-setup) first—this guide assumes that's done.

### AWS requirements

Your AWS environment must have:

* An **AWS Account** with Bedrock enabled in your target region.
* **Foundation model access** granted to the model your agent will use.
* The IAM user used by your Bedrock AI Provider must include the `bedrock:InvokeAgent` permission (see [Step 2](#step-2-grant-invokeagent-permission)).

<Warning>
  **Model access**: Confirm model access in the Amazon Bedrock console for your account and region; approval timing depends on AWS.
</Warning>

## Step 1: Configure the Bedrock Agent in AWS

If you have not yet built the agent in AWS, create it and an agent alias before connecting to Elementum. Skip to [Step 2](#step-2-grant-invokeagent-permission) if you already have a Bedrock Agent and alias.

### Create a Bedrock Agent in AWS

<Steps>
  <Step title="Access Amazon Bedrock">
    1. Sign in to the AWS Management Console.
    2. Navigate to the **Amazon Bedrock** service.
    3. Select **Agents** from the left navigation.
  </Step>

  <Step title="Create New Agent">
    Click **Create agent** and configure:

    * **Agent name**: Provide a descriptive name (e.g., "Customer Support Agent").
    * **Description**: Describe the agent's purpose.
    * **Agent resource role**: Create a new role or select an existing one with Bedrock permissions.
  </Step>

  <Step title="Configure Agent Instructions">
    Provide clear instructions that define the agent's behavior:

    ```
    You are a helpful customer support assistant. You help users with
    their questions about orders, returns, and product information.
    Always be polite and professional.
    ```

    <Tip>
      Clear, specific instructions lead to better agent performance. Include examples of expected behavior and any constraints.
    </Tip>
  </Step>

  <Step title="Select Foundation Model">
    Choose the foundation model to power your agent.

    <Info>
      Model availability depends on your region and account access. Request model access in the Bedrock console if needed.
    </Info>
  </Step>

  <Step title="Configure Optional Features">
    Optionally enhance your agent with:

    **Knowledge Bases:**

    * Attach Amazon Bedrock knowledge bases using supported data sources (for example, Amazon S3).
    * The agent can retrieve and cite that content when answering.

    **Action Groups:**

    * Define custom actions via Lambda functions.
    * Enable the agent to perform specific tasks.

    **Guardrails:**

    * Implement content filtering.
    * Define topic restrictions.
  </Step>

  <Step title="Save and Prepare">
    Click **Create** to save the agent configuration.

    The agent will be created in **Draft** status.
  </Step>
</Steps>

### Create an agent alias

Elementum invokes agents with an **Agent Alias ARN**, not the base agent ARN.

1. In the Bedrock console, open the agent and open the **Aliases** tab.
2. Click **Create alias**. Set an alias name and description, and choose **Create a new version and associate it to this alias** so the alias points at a prepared version.
3. After creation, copy the **Agent Alias ARN**. Format: `arn:aws:bedrock:{region}:{account-id}:agent-alias/{agent-id}/{alias-id}`

Example:

```
arn:aws:bedrock:us-east-2:123456789012:agent-alias/ABCD1234EF/GHIJ5678KL
```

### Test the agent in the AWS console

Before connecting to Elementum, verify your agent works correctly:

1. In the Bedrock console, open your agent.
2. Use the **Test** panel on the right side.
3. Send test messages to verify behavior.
4. Confirm responses match your expectations.

## Step 2: Grant InvokeAgent permission

The IAM user backing your Bedrock AI Provider must be able to invoke agents.

1. In the AWS Console, go to **IAM** and open the user used by your Bedrock AI Provider.

2. Edit the user's attached policy and add `bedrock:InvokeAgent` to the existing statement (alongside `bedrock:InvokeModel`):

   ```json theme={null}
   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "bedrock:InvokeModel",
           "bedrock:InvokeAgent"
         ],
         "Resource": "*"
       }
     ]
   }
   ```

   <Tip>
     **Least privilege**: For production, restrict the `Resource` to specific model and agent ARNs:

     ```json theme={null}
     "Resource": [
       "arn:aws:bedrock:us-east-2::foundation-model/*",
       "arn:aws:bedrock:us-east-2:123456789012:agent-alias/*"
     ]
     ```
   </Tip>

3. Save the policy.

<Info>
  If your agent uses knowledge bases or action groups, the agent's own IAM role (not the invoker role) needs additional permissions for those resources.
</Info>

## Step 3: Connect the agent in App Intelligence

### Open App Intelligence

1. Open the App where you want to use the Bedrock Agent.
2. In the App menu, click **Intelligence**.

### Connect the Bedrock agent

<Steps>
  <Step title="Add Agent">
    On the Intelligence page, click **+ Connect** (or the control your workspace uses to connect a managed agent).
  </Step>

  <Step title="Select Bedrock">
    Choose **Bedrock** as the agent source.
  </Step>

  <Step title="Select Provider">
    Choose your Amazon Bedrock AI Provider. Only providers with working credentials appear.
  </Step>

  <Step title="Enter Agent Alias ARN">
    Paste the **Agent Alias ARN** from [Create an agent alias](#create-an-agent-alias). Do not use the base agent ARN.
  </Step>

  <Step title="Configure Agent Settings">
    **Agent Name**: Optionally customize the display name in Elementum.

    **Description**: Add notes about how this agent will be used in your App.
  </Step>

  <Step title="Save Configuration">
    Click **Save** to connect the external agent.

    The agent will now appear in your App's Intelligence configuration.
  </Step>
</Steps>

## Step 4: Test the integration

Verify the agent connection works correctly.

### Test in Elementum

<Steps>
  <Step title="Open Agent">
    In App Intelligence, click on the connected Bedrock agent.
  </Step>

  <Step title="Start Chat">
    Click **Chat** to open the interactive testing panel.
  </Step>

  <Step title="Send Test Messages">
    Send messages to confirm:

    * The agent responds successfully.
    * Responses are appropriate and match expectations.
    * Latency is acceptable for your use case.
  </Step>

  <Step title="Verify Behavior">
    Test various scenarios relevant to your use case:

    * Standard queries.
    * Edge cases.
    * Knowledge base retrieval (if configured).
    * Action group execution (if configured).
  </Step>
</Steps>

### Expected behavior

| Test                     | Expected result                             |
| ------------------------ | ------------------------------------------- |
| Simple greeting          | Agent responds appropriately                |
| Domain-specific question | Agent uses knowledge base (if configured)   |
| Action request           | Agent executes action group (if configured) |
| Out-of-scope question    | Agent handles gracefully per instructions   |

## Step 5: Use the agent in automations

Use your Bedrock Agent in App automations for production workflows.

### Using agents in automation actions

In the automation builder, the action type is **Run Agent Task**. For full field-level detail, see [Run Agent Task](/workflows/automation-actions-reference) in the automation actions reference.

<Steps>
  <Step title="Navigate to Automation">
    In your App, open the automation where you want to use the agent.
  </Step>

  <Step title="Add Run Agent Task">
    Add a new action or edit an existing one, then choose **Run Agent Task**.
  </Step>

  <Step title="Select Bedrock Agent">
    Under **AI Agent** (or equivalent), choose the external Bedrock Agent you connected in Intelligence.

    It may appear as **External** or **Managed**, depending on your workspace.
  </Step>

  <Step title="Configure the task and outputs">
    **Task definition**: Describe what the agent should do and how success is judged. Use value references for record fields, prior action outputs, or static text where supported.

    **Output type**: Choose **Text** or **Structured**. For structured output, define fields so later automation steps can map results to records or variables.

    Configure any error or follow-up behavior your automation requires after the task completes.
  </Step>

  <Step title="Set Execution Options">
    **Timeout**: Set a maximum execution time that fits your agent and knowledge sources (the editor may suggest a default).

    **Retry Policy**: Configure retry behavior for transient failures.

    **Error Handling**: Define failure behavior:

    * Continue with default values.
    * Halt automation and alert.
    * Escalate to human review.
  </Step>
</Steps>

### Example automation (conceptual)

The following illustrates how steps might flow; exact builder labels can vary by release.

```yaml theme={null}
Workflow: Customer Inquiry Processing
Trigger: New inquiry record created
Automations:
  1. Gather Context:
     - Collect customer information
     - Retrieve previous interactions

  2. Run Agent Task – Analysis:
     Type: Run Agent Task
     Agent: Customer Support Agent (Bedrock / Managed)
     Inputs:
       - customer_inquiry: {record.description}
       - customer_history: {customer.interaction_history}
     Outputs:
       - response: record.suggested_response
       - category: record.inquiry_category
       - sentiment: record.customer_sentiment

  3. Route Based on Category:
     - High priority → Immediate escalation
     - Standard → Queue for review
     - FAQ → Auto-respond with suggestion
```

## How Bedrock Agent invocation works

When Elementum invokes a Bedrock Agent:

```mermaid theme={null}
sequenceDiagram
    participant Auto as Automation
    participant Intel as App Intelligence
    participant Prov as Bedrock AI Provider
    participant AWS as AWS Bedrock
    participant BA as Bedrock Agent
    participant KB as Knowledge Bases
    participant AG as Action Groups

    Auto->>Intel: Invoke External Agent
    Intel->>Prov: Route via Provider
    Prov->>AWS: InvokeAgent API
    AWS->>BA: Execute Agent
    BA->>KB: Query Knowledge (optional)
    KB->>BA: Return Context
    BA->>AG: Execute Actions (optional)
    AG->>BA: Return Results
    BA->>AWS: Generate Response
    AWS->>Prov: Return Response
    Prov->>Intel: Format Response
    Intel->>Auto: Continue Automation
```

### AWS Bedrock API used

**InvokeAgent** sends a prompt to the agent and returns the agent's response (including optional tool and knowledge-base steps on the AWS side).

**Key parameters:**

* `agentAliasId`: The alias ID of the agent.
* `agentId`: The unique identifier of the agent.
* `sessionId`: Session identifier for conversation continuity.
* `inputText`: The message to send to the agent.

**Documentation**: [Amazon Bedrock InvokeAgent API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html)

### Security model

| Aspect              | Implementation                                     |
| ------------------- | -------------------------------------------------- |
| **Authentication**  | IAM Access Key/Secret Key via Bedrock AI Provider  |
| **Authorization**   | IAM policies control which agents can be invoked   |
| **Data in transit** | TLS encryption for all API calls                   |
| **Audit**           | AWS CloudTrail logs all Bedrock API calls          |
| **Isolation**       | App-level configuration with provider-based access |

## Monitoring and Maintenance

### Monitoring agent performance

**In Elementum**

* Use automation history and related logs to review invocations, response times, success and failure rates, and error messages.

**In AWS**

* Use CloudWatch and Cost Explorer (as applicable) for Bedrock API volume, latency, errors, and token or usage-related metrics.

### Maintenance tasks

<Tabs>
  <Tab title="Regular Maintenance">
    **Weekly:**

    * Review automation logs for agent errors.
    * Monitor response times and latency.
    * Check for timeout patterns.

    **Monthly:**

    * Review agent usage and costs.
    * Audit IAM permissions.
    * Test agent behavior after any updates.

    **Quarterly:**

    * Rotate IAM access keys.
    * Review and optimize agent instructions.
    * Evaluate new foundation models.
  </Tab>

  <Tab title="Updating Agents">
    When updating Bedrock Agents:

    1. **Test in AWS**: Verify changes in the Bedrock console first.
    2. **Create New Alias**: Create a new alias for the updated version.
    3. **Update Elementum**: Update the Agent Alias ARN if using a new alias.
    4. **Test Integration**: Validate automations with the updated agent.
    5. **Monitor**: Watch for issues after deployment.

    <Tip>
      Use separate aliases for testing and production to safely test changes.
    </Tip>
  </Tab>

  <Tab title="Scaling">
    As usage grows:

    **AWS Side:**

    * Monitor Bedrock service quotas.
    * Request quota increases if needed.
    * Consider provisioned throughput for consistent performance.

    **Elementum Side:**

    * Monitor automation execution times.
    * Implement caching for repeated queries.
    * Use async patterns for long-running operations.
  </Tab>
</Tabs>

## Troubleshooting

<Accordion title="Access Denied Errors">
  **Error**: "Access Denied" or "Not authorized to perform bedrock:InvokeAgent".

  **Possible causes:**

  * IAM user missing `bedrock:InvokeAgent` permission.
  * Policy not attached to the user.
  * Resource restrictions in policy don't match the agent ARN.

  **Solutions:**

  1. Verify the IAM policy includes `bedrock:InvokeAgent` and is attached to the IAM user whose keys are on the Bedrock AI Provider (see [Step 2](#step-2-grant-invokeagent-permission)).
  2. Ensure the policy `Resource` matches your agent alias ARNs or uses a permitted pattern.
  3. Confirm the access keys in Elementum belong to that user.
</Accordion>

<Accordion title="ARN Format Errors">
  **Error**: "Invalid ARN format" or "Resource not found".

  **Possible causes:**

  * Using the base agent ARN instead of the agent alias ARN.
  * Typo in the ARN.
  * Wrong region in the ARN.

  **Solutions:**

  1. Ensure you're using the **Agent Alias ARN**, not the base Agent ARN.
  2. Verify the format: `arn:aws:bedrock:{region}:{account}:agent-alias/{agent-id}/{alias-id}`
  3. Copy the ARN directly from the AWS console.
  4. Check that the region matches your provider configuration.

  **Correct format:**

  ```
  arn:aws:bedrock:us-east-2:123456789012:agent-alias/ABCD1234EF/GHIJ5678KL
  ```

  **Incorrect (base agent ARN):**

  ```
  arn:aws:bedrock:us-east-2:123456789012:agent/ABCD1234EF
  ```
</Accordion>

<Accordion title="Region Mismatch">
  **Error**: "Could not connect to endpoint" or timeout errors.

  **Possible causes:**

  * Provider configured for a different region than the agent.
  * Agent not available in the specified region.

  **Solutions:**

  1. Verify the region in your Bedrock AI Provider matches where the agent is deployed.
  2. Check the region in the Agent Alias ARN.
  3. Confirm Bedrock is available in your target region.
  4. Update provider configuration if needed.
</Accordion>

<Accordion title="Timeout Errors">
  **Error**: "Agent execution timed out".

  **Possible causes:**

  * Timeout set too low for agent complexity.
  * Agent accessing slow knowledge bases.
  * Large response generation.
  * Network latency.

  **Solutions:**

  1. Increase timeout in automation configuration.
  2. Optimize agent instructions for faster responses.
  3. Review knowledge base configuration for performance.
  4. Consider breaking complex tasks into multiple calls.
</Accordion>

<Accordion title="Alias Not Associated with Version">
  **Error**: "Alias has no associated version" or unexpected behavior.

  **Possible causes:**

  * Alias created without linking to a version.
  * Agent in draft state without prepared version.

  **Solutions:**

  1. In the Bedrock console, verify the alias has an associated version.
  2. Create a new alias and select "Create a new version and associate it".
  3. Ensure the agent is not in draft state.
</Accordion>

### Debugging tips

1. **Test in AWS first**: Always verify the agent works in the Bedrock console before troubleshooting Elementum integration.
2. **Check CloudTrail**: Review AWS CloudTrail logs for detailed API call information.
3. **Verify credentials**: Test IAM credentials independently using the AWS CLI.
4. **Review provider status**: Check the Bedrock AI Provider status in Elementum.

## Best Practices

<AccordionGroup>
  <Accordion title="Agent configuration and guardrails">
    * Use Bedrock Guardrails and clear instruction scope where appropriate.
    * Review agent behavior and access periodically.
  </Accordion>

  <Accordion title="Optimize instructions">
    Clear, concise agent instructions usually produce faster, more predictable responses. Prefer explicit scope, examples, and constraints over long generic prompts.
  </Accordion>

  <Accordion title="Latency and timeouts">
    Track response times in automations and in AWS where you have metrics. Set automation timeouts high enough for knowledge-base retrieval and tool use, without masking real failures.
  </Accordion>

  <Accordion title="Caching repeated work">
    Where the same or similar agent inputs occur often, consider caching or deduplicating at the automation level so you do not pay latency and usage for identical work.
  </Accordion>

  <Accordion title="Rate limiting high-volume automations">
    For automations that invoke agents at high volume, add throttling or batching so you stay within quotas and avoid unnecessary parallel cost spikes.
  </Accordion>

  <Accordion title="Knowledge base footprint">
    Review knowledge base size, refresh cadence, and retrieval settings so you are not indexing or retrieving more content than the agent needs.
  </Accordion>
</AccordionGroup>

## Example Use Cases

<AccordionGroup>
  <Accordion title="IT helpdesk automation">
    **Scenario:** Automatically triage and respond to IT support tickets.

    **Implementation:**

    1. Create a Bedrock Agent with an IT knowledge base (documentation, FAQs).
    2. Configure action groups for ticket operations.
    3. Connect the agent in the IT Support App Intelligence.
    4. Set up automation: New ticket → Agent analysis → Auto-categorize and suggest resolution.

    **Outcomes:**

    * Faster first response times.
    * Consistent ticket categorization.
    * Reduced L1 support workload.
  </Accordion>

  <Accordion title="Customer communication">
    **Scenario:** Generate personalized customer communications.

    **Implementation:**

    1. Create a Bedrock Agent with communication templates and brand guidelines.
    2. Configure guardrails for appropriate content.
    3. Connect the agent in the CRM App.
    4. Automation: Communication request → Agent drafts message → Human review → Send.

    **Outcomes:**

    * Consistent brand voice.
    * Personalized content at scale.
    * Faster communication turnaround.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="AWS Bedrock Setup" icon="aws" href="/ai-agents/bedrock-setup">
    Configure the Bedrock provider for AI Services (prerequisite for this guide)
  </Card>

  <Card title="Automation System" icon="robot" href="/workflows/automation-system">
    Build automations that invoke your Bedrock Agent
  </Card>

  <Card title="Agents Overview" icon="brain" href="/ai-agents/agents-overview">
    Compare native Elementum agents with managed external agents
  </Card>

  <Card title="AWS Bedrock Agents Docs" icon="aws" href="https://docs.aws.amazon.com/bedrock/latest/userguide/agents.html">
    Reference AWS's official Bedrock Agents documentation
  </Card>
</CardGroup>