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:
| Identity | What it is | Used for |
|---|---|---|
| Willow IAM identity | The IAM user (or role) whose access key you paste into Willow. | Willow uses it to create, update, and invoke harnesses in your account. |
| Execution role | An 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). Anthropic (Claude) models also need the one-time use case details form submitted in the Bedrock console (Model catalog, open any Anthropic model); until then every run fails, see Troubleshooting.
- 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.
- In the AWS Console, go to IAM → Roles → Create role.
- Choose Custom trust policy and paste:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": { "Service": "bedrock-agentcore.amazonaws.com" },
"Action": "sts:AssumeRole"
}
]
}
- Attach a permissions policy that lets the harness invoke Bedrock models, pull its managed image, write logs and traces, and use its memory. This is the AWS sample execution role policy — replace
<region>and<accountId>:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "BedrockModelInvocation",
"Effect": "Allow",
"Action": [
"bedrock:InvokeModel",
"bedrock:InvokeModelWithResponseStream"
],
"Resource": [
"arn:aws:bedrock:*::foundation-model/*",
"arn:aws:bedrock:<region>:<accountId>:*"
]
},
{
"Sid": "EcrPublicPull",
"Effect": "Allow",
"Action": ["ecr-public:GetAuthorizationToken", "sts:GetServiceBearerToken"],
"Resource": "*"
},
{
"Sid": "XRayTracing",
"Effect": "Allow",
"Action": [
"xray:PutTraceSegments",
"xray:PutTelemetryRecords",
"xray:GetSamplingRules",
"xray:GetSamplingTargets"
],
"Resource": "*"
},
{
"Sid": "CloudWatchLogs",
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:DescribeLogStreams",
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": "arn:aws:logs:<region>:<accountId>:log-group:/aws/bedrock-agentcore/runtimes/*"
},
{
"Sid": "CloudWatchLogsAccount",
"Effect": "Allow",
"Action": ["logs:DescribeLogGroups", "logs:PutResourcePolicy"],
"Resource": "*"
},
{
"Sid": "CloudWatchMetrics",
"Effect": "Allow",
"Action": "cloudwatch:PutMetricData",
"Resource": "*",
"Condition": { "StringEquals": { "cloudwatch:namespace": "bedrock-agentcore" } }
},
{
"Sid": "AgentCoreWorkloadIdentity",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:GetWorkloadAccessToken",
"bedrock-agentcore:GetWorkloadAccessTokenForJWT"
],
"Resource": [
"arn:aws:bedrock-agentcore:<region>:<accountId>:workload-identity-directory/default",
"arn:aws:bedrock-agentcore:<region>:<accountId>:workload-identity-directory/default/workload-identity/harness_*"
]
},
{
"Sid": "AgentCoreMemory",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:CreateEvent",
"bedrock-agentcore:DeleteEvent",
"bedrock-agentcore:GetEvent",
"bedrock-agentcore:ListEvents",
"bedrock-agentcore:RetrieveMemoryRecords"
],
"Resource": "arn:aws:bedrock-agentcore:<region>:<accountId>:memory/*"
}
]
}
The AgentCoreMemory resource is memory/* rather than the memory/harness_* shown in the AWS sample: the harness names its memory after the harness (for example memory/willow_support_triage-AbC123), without the harness_ prefix, so the narrower pattern makes every run fail with AccessDeniedException ... bedrock-agentcore:ListEvents.
If the agent uses the AgentCore code interpreter or browser tools, also add the AgentCoreCodeInterpreterDefault and AgentCoreBrowserDefault statements from the same AWS page.
- Name the role (for example
willow-background-agents) and create it. - 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.
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.
- Use an existing IAM user or create one (for example
willow-agentcore). - Attach an inline policy granting harness management, invocation, and
iam:PassRoleon the execution role:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ManageHarnesses",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:CreateHarness",
"bedrock-agentcore:UpdateHarness",
"bedrock-agentcore:GetHarness",
"bedrock-agentcore:ListHarnesses",
"bedrock-agentcore:InvokeHarness",
"bedrock-agentcore:CreateAgentRuntime",
"bedrock-agentcore:UpdateAgentRuntime",
"bedrock-agentcore:GetAgentRuntime",
"bedrock-agentcore:ListAgentRuntimes",
"bedrock-agentcore:InvokeAgentRuntime",
"bedrock-agentcore:CreateAgentRuntimeEndpoint",
"bedrock-agentcore:UpdateAgentRuntimeEndpoint",
"bedrock-agentcore:GetAgentRuntimeEndpoint",
"bedrock-agentcore:CreateWorkloadIdentity",
"bedrock-agentcore:UpdateWorkloadIdentity",
"bedrock-agentcore:GetWorkloadIdentity",
"bedrock-agentcore:CreateMemory",
"bedrock-agentcore:UpdateMemory",
"bedrock-agentcore:GetMemory",
"bedrock-agentcore:ListMemories",
"bedrock-agentcore:TagResource"
],
"Resource": "*"
},
{
"Sid": "ListUsableModels",
"Effect": "Allow",
"Action": [
"bedrock:ListFoundationModels",
"bedrock:ListInferenceProfiles",
"bedrock:GetFoundationModelAvailability",
"bedrock:GetUseCaseForModelAccess"
],
"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.
A harness runs on AgentCore Runtime and Memory, so AWS checks the matching runtime and memory actions on every harness call: creating a harness also needs CreateAgentRuntime and CreateMemory, and invoking one also needs InvokeAgentRuntime (on the harness/... ARN). After the create or update call returns, AWS keeps provisioning in the background with the same identity: it creates the runtime endpoint (CreateAgentRuntimeEndpoint), the runtime's workload identity (CreateWorkloadIdentity), and reads the memory back (GetMemory). If any of these is missing, the harness ends in CREATE_FAILED or UPDATE_FAILED and the sync reports why — see Verify the harness. TagResource is needed because Willow tags each harness with its agent and organization. GetAgentRuntime and ListAgentRuntimes let Willow discover agents that already exist in the account. The read-only ListUsableModels actions let Willow offer only the Bedrock models your account can actually run; without them the model picker lists every model and a model your account can't use fails on the first run. See Required IAM permissions for callers in the AWS docs.
- Create an access key for the identity and copy the Access Key ID and Secret Access Key.
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
- Go to Build → Background Agents (see the list page), open Settings (gear icon), select the Platforms tab, and find AWS AgentCore in the Agent Types card.
- 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.
- Select Connect. The secret key is encrypted at rest and only used server-side to manage your harnesses.
The card shows Key set and the platform switches on. AWS AgentCore is now a selectable platform when creating an agent.
Step 4: Sync and verify the harness
- Create an agent and choose AWS AgentCore as the platform. Under Settings, Platform, pick a Bedrock Model. The list shows only the Claude and Amazon Nova models your account can run in the connected region; Claude models appear once the Anthropic use case form is submitted. Choose a model before selecting Sync.
- Select Sync in the detail-page header (Sync changes once there are edits the harness has not received, Resync otherwise). It creates or updates the harness with the latest definition, tools, and refreshed credentials. See Deploy an Agent.
- Wait for the sync to finish. AWS provisions the harness in the background after accepting the request, and Willow waits about 20 seconds for it to reach
READY. A first create can take longer, and AWS keeps provisioning after Willow stops waiting. If you sync again while the harness is stillCREATINGorUPDATING, the sync stops with "AWS is still creating this harness … Sync again once it's ready"; wait a few minutes and select Resync. If provisioning fails, the sync fails with "The harness is CREATE_FAILED: …" (orUPDATE_FAILED) followed by AWS's reason. To check the harness yourself:
aws bedrock-agentcore-control list-harnesses --region <region> \
--query 'harnesses[].[harnessName,harnessId,status]' --output table
aws bedrock-agentcore-control get-harness --region <region> --harness-id <harnessId> \
--query 'harness.[status,failureReason]' --output text
The harness is named willow_<agent_slug> (dashes become underscores). CREATING and UPDATING take a few seconds; READY means it is ready to run. On CREATE_FAILED or UPDATE_FAILED, failureReason names the missing action — add it, wait about 30 seconds for IAM to propagate, and select Resync.
- Select Test on the agent and send a message, for example "Run
echo helloin your shell and tell me the output." The agent's reply and each tool it calls appear in the panel as they stream from AgentCore. The first run on a new harness can take 30 seconds or more while AgentCore starts the runtime. If the run fails, the panel shows AWS's error message instead of a reply. - Open the Sessions tab to see every conversation the agent has had through Willow, including Test sessions, with the full transcript. For lower-level detail, the runtime log group in CloudWatch is
/aws/bedrock-agentcore/runtimes/harness_willow_<agent_slug>-*.
Git repositories
To let the agent clone and push GitHub repositories, set up Git Proxy and list the repositories under the agent's Settings, Git repositories, then Sync changes. Willow adds the WILLOW_* environment variables and git instructions to the harness. The agent configures git with its built-in shell, so you don't need a custom container image.
Set up with the AWS CLI
Steps 1 and 2 can be scripted instead of done in the console. Save the trust policy from Step 1 as trust.json, the execution role policy as exec-policy.json, and the Willow identity policy from Step 2 as willow-policy.json (with your account, region, and role name filled in), then run:
# Step 1: execution role
aws iam create-role --role-name willow-background-agents \
--assume-role-policy-document file://trust.json
aws iam put-role-policy --role-name willow-background-agents \
--policy-name harness-execution --policy-document file://exec-policy.json
# Step 2: Willow IAM identity and its access key
aws iam create-user --user-name willow-agentcore
aws iam put-user-policy --user-name willow-agentcore \
--policy-name willow-agentcore --policy-document file://willow-policy.json
aws iam create-access-key --user-name willow-agentcore
create-access-key prints the AccessKeyId and SecretAccessKey to paste into Willow in Step 3, and create-role prints the role Arn. To check the policy before syncing:
aws iam simulate-principal-policy \
--policy-source-arn arn:aws:iam::<accountId>:user/willow-agentcore \
--action-names bedrock-agentcore:CreateHarness bedrock-agentcore:InvokeHarness \
--query 'EvaluationResults[].[EvalActionName,EvalDecision]' --output text
Troubleshooting
Sync fails with The harness is CREATE_FAILED or UPDATE_FAILED
AWS accepted the harness but was denied a step while provisioning it in the background. The reason after the colon is usually one of CreateAgentRuntimeEndpoint, CreateWorkloadIdentity, or HTTP 403 from memory service (GetMemory), all on the Willow IAM identity. Add the actions from the Step 2 policy, wait about 30 seconds for IAM to propagate, and Resync.
Test fails with AccessDeniedException on memory/...
The harness is READY but the run failed inside AgentCore. A denial on an assumed-role/<execution role>/... principal is the execution role from Step 1, most often bedrock-agentcore:ListEvents on memory/... because the memory statement is scoped to memory/harness_* instead of memory/*. The runtime log group (/aws/bedrock-agentcore/runtimes/harness_willow_<agent_slug>-*) has the full error.
Test fails with Model use case details have not been submitted for this account
The agent uses an Anthropic (Claude) model and the AWS account has not submitted Anthropic's use case form. In the Bedrock console, open Model catalog, select any Anthropic model, and submit the form. Access is usually granted within minutes, after which Claude models appear in the agent's Bedrock Model list. Until then, pick an Amazon Nova model under the agent's Settings, Platform, then Sync changes.
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
ResourceARN matches the execution role character-for-character. - If you used a
Conditiononiam: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.
not authorized to perform: bedrock-agentcore:<Action>
For example bedrock-agentcore:TagResource or CreateAgentRuntime on Sync, or InvokeAgentRuntime on Test. This is the Willow IAM identity policy, not the execution role: add the action named in the error to the ManageHarnesses statement from Step 2. If you scoped Resource instead of using *, note that runtime actions are checked against the harness/... ARN, so runtime/* alone is not enough.
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).