Skip to main content

Connect AWS AgentCore

AWS AgentCore lets a background agent run as an Amazon Bedrock AgentCore harness in your own AWS account. Willow syncs the agent definition, its gateway tools, and a scoped access token to the harness, and the harness calls those tools back through the Willow gateway.

Connecting the platform involves two AWS identities that are easy to confuse:

IdentityWhat it isUsed for
Willow IAM identityThe IAM user (or role) whose access key you paste into Willow.Willow uses it to create, update, and invoke harnesses in your account.
Execution roleAn IAM role that the AgentCore service assumes when a harness runs.Gives the running agent permission to invoke Bedrock models.

The two most common setup errors both come from mixing these up:

  • Passing the Willow IAM user ARN where an execution role ARN is required.
  • The Willow IAM identity not being allowed to pass the execution role to AgentCore (iam:PassRole).

Follow the steps below in order and both are avoided.

Prerequisites​

  • An AWS account with Amazon Bedrock AgentCore available in your chosen region (Willow defaults to us-west-2).
  • Model access enabled in Bedrock for the model the agent will use (for example a Claude or Amazon Nova model).
  • Permission to create IAM roles and policies in that account.

Step 1: Create the execution role​

This is the role the AgentCore service assumes to run your agent. It must be an IAM role — not a user — with a trust policy that lets the AgentCore service assume it.

  1. In the AWS Console, go to IAM → Roles → Create role.
  2. Choose Custom trust policy and paste:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "bedrock-agentcore.amazonaws.com" },
      "Action": "sts:AssumeRole"
    }
  ]
}
  1. Attach a permissions policy that lets the harness invoke Bedrock models, for example:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": "*"
    }
  ]
}
  1. Name the role (for example willow-background-agents) and create it.
  2. Copy the role ARN — it looks like arn:aws:iam::123456789012:role/willow-background-agents. You'll paste this into Willow as the Execution Role ARN.
note

The ARN must contain :role/. An IAM user ARN (:user/...) is rejected with a validation error because AgentCore only accepts a role in this field.

Step 2: Prepare the Willow IAM identity​

Willow needs an access key for an IAM identity that is allowed to manage harnesses and pass the execution role from Step 1.

  1. Use an existing IAM user or create one (for example willow-agentcore).
  2. Attach an inline policy granting harness management, invocation, and iam:PassRole on the execution role:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ManageHarnesses",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreateHarness",
        "bedrock-agentcore:UpdateHarness",
        "bedrock-agentcore:ListHarnesses",
        "bedrock-agentcore:InvokeHarness"
      ],
      "Resource": "*"
    },
    {
      "Sid": "PassExecutionRole",
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::123456789012:role/willow-background-agents"
    }
  ]
}

Replace the account id and role name with your own. iam:PassRole is what lets this identity hand the execution role to AgentCore — without it the sync fails with an AccessDeniedException.

  1. Create an access key for the identity and copy the Access Key ID and Secret Access Key.
tip

You can scope iam:PassRole further with a Condition such as "iam:PassedToService": "bedrock-agentcore.amazonaws.com". Only add it once you've confirmed the sync works without it — a mismatched service value causes the same PassRole denial and is a common cause of a sync that "still fails after adding the policy".

Step 3: Connect the platform in Willow​

  1. Go to Build → Background Agents, open Settings (gear icon), and find AWS AgentCore under Agent Types.
  2. Select Set credentials and enter:
    • AWS Access Key ID and AWS Secret Access Key from Step 2.
    • Region — the region where AgentCore and your model access are enabled (default us-west-2).
    • Execution Role ARN — the role ARN from Step 1.
  3. Select Connect. The secret key is encrypted at rest and only used server-side to manage your harnesses.

Once connected, AWS AgentCore appears as a selectable platform when creating an agent. Managed platforms keep an external copy in sync — the agent's detail page shows a Sync action to push the latest definition, tools, and refreshed credentials to the harness.

Troubleshooting​

executionRoleArn ... failed to satisfy constraint: ... :role/.+​

The value in Execution Role ARN is not a role ARN. Make sure it points to an IAM role (arn:aws:iam::<account>:role/<name>), not an IAM user (:user/...) — see Step 1.

not authorized to perform: iam:PassRole ... no identity-based policy allows the iam:PassRole action​

The Willow IAM identity is missing iam:PassRole for the execution role. Add the PassExecutionRole statement from Step 2. If you already added it and still see this error:

  • Confirm the policy is attached to the exact identity named in the error message.
  • Confirm the Resource ARN matches the execution role character-for-character.
  • If you used a Condition on iam:PassRole, remove it and retry — the condition value likely doesn't match the service that AgentCore passes the role to.
  • Check for a Service Control Policy or permissions boundary that explicitly denies iam:PassRole; an explicit deny overrides your allow.

The harness fails to run after a successful sync​

The sync (create/update) uses the Willow IAM identity, but running the harness uses the execution role. If the sync succeeds but runs fail, verify the execution role's trust policy allows bedrock-agentcore.amazonaws.com to assume it and that it has Bedrock model invocation permissions (both from Step 1).

What to do next​

On this page