AI-narrated article. Prose is preserved with pronunciation adjustments; code and image cues refer to the written article.
AWS AI Agents: Bind Identity, Tool Authority and Cost to the Same Task
This is the AI-narrated article. The prose follows the written post; pronunciation is adjusted, and code and images are announced separately.
Build an AgentCore tool whose caller, backend permissions, trace evidence and operating cost stay connected without sharing administrator authority.
TL;DR: Production agents need more than a model and a collection of tools. Separate authenticated caller identity, AgentCore workload identity, Gateway authorization and backend IAM permissions. Implement a fixed-resource Lambda tool, permit its exact action on one Gateway, and keep deployment administration outside the runtime. Correlate authorization and target outcomes with application task ownership while protecting credentials and sensitive content. Budget inference, runtime, tool and telemetry consumption across successful and failed attempts. This article provides a reviewed configuration package and a documented denial-recovery path; no AWS deployment or cloud measurement was executed.
An agent that can explain a failed release may also be able to retrieve secrets, retry expensive inference indefinitely or act through a shared administrator role. The model's intention does not establish which customer, account or resource a tool invocation belongs to. Production ownership starts with four separate questions: who called, which credential reaches the target, what action is allowed, and what each completed task costs.
Amazon Bedrock AgentCore provides building blocks for these boundaries. The architecture still has to connect them correctly. This example designs one application-owned cluster-summary tool, rather than granting an agent a general AWS command executor. It is a reviewed implementation package; no AWS resources were created and no cloud invocation or performance measurement was executed.
Keep caller identity separate from execution authority
A Gateway's inbound identity and its outbound credential solve different problems. With AWS_IAM authentication, the caller is an IAM identity. With OAuth, Policy represents the authenticated subject using the JWT sub claim. A shared runtime role therefore does not automatically identify the human who initiated a task. Carry an application-verified task owner in your audit record; never accept a model-generated user ID as authorization evidence. Gateway authorization
AgentCore workload identity is a stable identity for agents accessing credentials across authentication schemes; Runtime and Gateway can create it automatically. It does not replace tenant membership. Scope the actual requesting IAM role's credential-retrieval permissions to approved provider resources; sharing an account or vault must not imply permission to retrieve every provider's credentials. For delegated OAuth, preserve the intended user-consent flow rather than substituting a shared machine credential. This Lambda target instead uses the Gateway IAM role, so it needs no OAuth provider. Workload identities, provider access scoping
Separate the caller role, Gateway execution role, Lambda execution role and administrator role. The administrator owns target definitions, policies and credential bindings. Keep iam:PassRole and resource-management capabilities outside the agent's runtime role. Otherwise the agent can potentially change the boundary it is supposed to obey. Role separation
Image. Authority cards: caller identity, Gateway authorization, target credential and operational ownership
The diagram shows independent responsibilities. A tool permission does not enlarge its backend IAM role; a backend credential does not establish the caller's entitlement.
Implement a resource-bound tool, not a cloud shell
Prerequisites are an existing, owner-approved EKS cluster, a Python 3.12 Lambda function, an AWS_IAM-authenticated AgentCore Gateway and an attached enforcing Policy engine in a supported Region. Package a tested Boto3/Botocore dependency pair with the Lambda deployment rather than depending on a changing runtime SDK. Record those resolved package versions in your deployment lockfile. This article uses current Gateway schemas and Cedar-compatible policy syntax; it does not pin a starter-toolkit CLI version.
The platform owner configures APPROVED_CLUSTER and APPROVED_REGION. Give the Lambda role eks:DescribeCluster on exactly that cluster ARN, plus separately scoped logging permissions. Give the Gateway role lambda:InvokeFunction on this function or its approved alias. Give the caller bedrock-agentcore:InvokeGateway on this Gateway. These are separate IAM policies; do not combine their actions into one shared role. EKS supports resource scoping for DescribeCluster. EKS authorization reference
Save this as lambda_function.py. The handler accepts no resource selector and returns only a small operational summary. The SDK has bounded connection/read timeouts and retries; configure the Lambda timeout above the resulting request budget.
Code example. Refer to the written article for the complete code.
Gateway passes tool arguments directly as the Lambda event and tool metadata through context.client_context.custom. Visible tool names include the target name and three underscores. The handler checks the complete name; it does not dispatch arbitrary function names. Lambda target contract, tool naming, SDK configuration
Save this complete target-config.json, replacing the illustrative Lambda ARN. The schema advertises no arguments; the handler independently rejects extra properties.
Code example. Refer to the written article for the complete code.
After approval, an owner with a current AWS CLI v2 exposing this command can register the target on the existing Gateway. This command creates a remote target; it was not executed for this article. Keep it in the owner's deployment workflow. Target configuration, CLI reference
Code example. Refer to the written article for the complete code.
Authorize the exact tool and Gateway
Replace the illustrative account, role and Gateway identifiers with the deployed resources. This permit admits one IAM caller identity and one action on one Gateway:
Code example. Refer to the written article for the complete code.
AgentCore documents a stable assumed-role principal identifier without a session-name suffix. Policies are validated against the Gateway-generated schema; verify the discovered tool name before creation. Current Policy supports Dogwood, a Cedar-compatible language; this example uses its ordinary Cedar subset. Default deny applies when no permit matches, and an applicable forbid overrides a permit. Principal and policy semantics, exact scope
Do not substitute a target-wide action group merely for convenience: adding a new tool to that target can enlarge the allowed surface. A shared caller role still represents the application, not individual users. If this tool becomes tenant-selectable, redesign the caller-to-resource binding and backend IAM scope before adding a clusterName argument.
Before rollout, validate a matrix covering the intended caller, another caller, an unknown action and extra arguments. Expected outcomes are design assertions, not results observed here. Also verify that the Gateway's execution role has GetPolicyEngine, AuthorizeAction and PartiallyAuthorizeActions scoped to the documented Policy engine/Gateway resources. Keep control-plane permissions with the deployment owner.
For local review, run python -m py_compile lambda_function.py and python -m json.tool target-config.json; neither invokes AWS. Remove generated __pycache__ afterward. Retiring the tool requires owner-controlled target/policy removal before IAM revocation; local deletion does not revoke remote access.
Make traces explain authority without retaining secrets
Record application task ID, verified owner reference, Gateway/tool identifiers, request ID, authorization outcome, target outcome, latency and retry count. Associate model usage with the same task in application telemetry. Avoid logging access tokens, API keys or complete prompts merely to make correlation easy. A task identifier helps join evidence; it is not an authorization credential.
AgentCore observability requires the relevant resource configuration and permissions. Identity telemetry includes workload and credential-provider identifiers, API operation, latency and errors. Decide retention, access and redaction before collecting sensitive inputs or tool responses. Do not promise that every application attribute appears automatically in service-generated telemetry. Observability setup, Identity telemetry
Budget complete tasks, including failed attempts
Account for model inference, Runtime consumption, Gateway operations and tool-search activity, target execution and telemetry. Identity pricing distinguishes standalone non-AWS credential requests from usage through Runtime or Gateway; observability storage and ingestion follow CloudWatch pricing. Recheck the pricing page for the selected components instead of assuming a single flat charge for an agent. AgentCore pricing
Use accepted tasks as a useful application denominator, while retaining failed and abandoned attempts in total cost. Track tokens, tool calls, retries and wall-clock duration separately. Application-enforced iteration, token and deadline limits bound work more directly than a retrospective billing alert. These controls are engineering choices, not a guarantee that every external charge stops immediately.
Bedrock cost attribution and request-level metadata are distinct. A shared IAM principal aggregates activity unless another supported attribution mechanism is deliberately configured. Request metadata in invocation logs does not automatically become an invoice allocation tag. Keep sensitive customer information out of attribution labels. Bedrock cost tracking
Recover denial without dismantling the boundary
Consider an illustrative rollout where the tool works before Policy attachment, then all calls fail. Missing Gateway execution-role Policy permissions can cause attachment errors or default-denied invocations even when a permit exists. Inspect the Gateway association, policy validation state, exact action/principal and execution-role permissions before widening a policy. Repair the missing scoped permission through the owner workflow, then rerun the positive and negative authorization cases. Documented failure modes
Does a workload identity identify the end user? No. Bind application ownership to authenticated caller evidence separately.
Does allowing a tool grant broader AWS access? Its backend role and implementation determine resource access; both must remain narrow.
Can traces alone prove cost per user? Only when identity and usage attribution are explicitly connected; shared-role totals cannot supply that mapping.