Amazon Bedrock Agents turn model reasoning into action through action groups. An action group describes functions or an OpenAPI-defined API surface that the agent may choose during orchestration. Bedrock can pass the requested action to a Lambda function for fulfillment, or it can return control to the application so the application decides how to execute the action. That execution choice is central to the security and reliability design.
Under the Generative AI on AWS architecture, Bedrock Agents Tool Use is the managed-agent path for tools. It is different from client-side Converse tool use and different from AgentCore Gateway. The existing Amazon Bedrock Agents article provides the broader orchestration context.
Tool use should be designed as a contract: what the model may request, how arguments are validated, who authorizes the action, and how the result is returned to the reasoning loop.
Action groups define the capabilities the agent can request
An action group can be defined with function details or through an OpenAPI schema. The names, descriptions, parameters, and schema influence which capability the model selects and how it constructs arguments.
Descriptions should be precise enough to distinguish similar tools. If two action groups both sound like “get customer data,” the model may route unpredictably. Parameters should constrain required fields and types instead of forcing a downstream function to recover missing business context from free text.
Tool schema quality is part of model quality because the model only sees the contract the application provides.
Lambda fulfillment centralizes business logic outside the model
Bedrock can invoke a configured Lambda function after the model selects an action and gathers the required parameters. The Lambda function receives the action context, performs the business logic, and returns a result for the agent to incorporate into the next reasoning step.
This pattern keeps side effects out of the foundation model. IAM and Lambda resource policies determine whether Bedrock may invoke the function, while the function itself can perform application authorization, input validation, transactions, and downstream calls.
The planned Lambda for GenAI Backends article covers how serverless functions fit into broader GenAI application architecture.
Return control is useful when the application must own the execution
An action group can use RETURN_CONTROL instead of Lambda fulfillment. In that mode, Bedrock returns the predicted action and parameters to the application through the agent response. The application can inspect, approve, modify, or execute the action and then continue the interaction.
This is useful for high-impact operations, systems that already have an application-side transaction layer, or environments where tool execution cannot be placed inside the Bedrock-owned Lambda path.
Return control also makes human approval easier because the application can stop before execution and present the proposed action to the user or reviewer.
Authorization should be checked at execution time
The model choosing a tool does not prove the user is authorized to use it. Authorization should be enforced by the Lambda function or application that executes the action, using trusted identity and resource context.
A support agent may have an action called “issue refund,” but the execution layer still needs to verify the user, order, amount, policy, and any approval threshold. Prompt instructions cannot replace those checks.
The existing API security article applies directly because agent actions are API requests generated through a model-mediated interface.
Tool retries need to distinguish reasoning from fulfillment
A Bedrock agent may decide to call an action again after receiving an error, but the downstream action can have side effects. If the first request succeeded and only the response was lost, another execution can duplicate the business operation.
High-impact tools should support idempotency keys or read-after-write recovery so the fulfillment layer can recognize a replay. Transient technical errors can be retried safely only when the operation semantics support it.
The agent’s reasoning loop should not become an uncontrolled retry engine for payments, deployments, account changes, or other non-idempotent work.
Tool results should be treated as data, not trusted instructions
A tool can return text from databases, websites, tickets, or other systems. That text can contain malicious or irrelevant instructions. The agent should treat tool output as evidence for the user task, not as a new privileged system prompt.
The planned Prompt Injection Defenses on AWS article goes deeper into this threat. Tool descriptions, argument validation, output sanitization, and separation of instructions from untrusted content all contribute.
Guardrails can add content controls, but they do not remove the need to design the tool boundary defensively.
Observability should show the action selected and the outcome returned
When an agent gives a wrong final answer, operators need to know whether the wrong tool was selected, the arguments were wrong, the tool failed, or the tool returned correct data that the model misinterpreted.
Trace data should therefore correlate the agent turn, action group, function or API name, parameters where safe, fulfillment latency, downstream status, and response. Sensitive arguments can be redacted or hashed while preserving the ability to diagnose the path.
The existing GenAI observability article provides the broader telemetry principles.
Tool catalogs should be smaller than the organization’s entire API estate
An agent does not need every available enterprise action. Too many similar tools increase selection ambiguity and expand the security surface. Action groups should be scoped to the agent’s actual job and organized so the model can distinguish them reliably.
If the organization needs a broader shared tool plane across several agents, Amazon Bedrock AgentCore Gateway may be a better platform boundary than duplicating the same tools into each Bedrock Agent.
Tool use works best when capability is intentional: a small set of clear actions, deterministic authorization, safe fulfillment, and observable outcomes.
Managed tool use should make the business boundary clearer, not hide it
Bedrock Agents reduce orchestration code, but they should not make business execution opaque. The application team should still know which component owns validation, authorization, transactionality, retry, audit, and human approval for every action group.
A mature design can explain what happens from the moment the model requests a tool to the moment the business system commits the change. That is the point at which model autonomy becomes a controlled production workflow rather than an impressive demo.
Action-group versioning should be coordinated with agent evaluation. Changing an OpenAPI schema or function description can change which tool the model selects even if the Lambda code itself is unchanged. Production releases should therefore treat tool-schema edits as behavior changes and rerun representative conversations before promotion.
Parameter elicitation deserves testing too. An agent may need to ask the user for missing information before it can invoke an action. The questions should be understandable, and the collected values should be validated again at the execution boundary. A model successfully eliciting an account number does not prove the number belongs to the authenticated user.
Action results should use structured, concise responses where possible. Returning a large unfiltered API payload increases token use and gives the model more irrelevant or potentially malicious text to interpret. The fulfillment layer can often reduce the result to the fields needed for the next reasoning step while retaining the full transaction record outside the prompt.
Human approval should be tied to the proposed action, not only the conversation. When an operation requires review, show the actual resource, parameters, and effect the tool will execute. “Approve agent request” is too vague for high-impact changes because the model may have translated a broad user goal into a specific action the user did not anticipate.
Finally, tool catalogs should be tested for confusion. Give the agent prompts that sit near the boundary between two actions and observe which tool it selects. If the model frequently chooses the wrong one, improve names and descriptions or separate the capabilities rather than adding prompt instructions that try to compensate for an ambiguous contract.
Session attributes and action context should be used carefully. Bedrock Agents can carry session-level information that helps a tool understand the current interaction, but that data should not become an unvalidated source of privilege. Tenant IDs, user IDs, and approval state should be derived from trusted application context whenever they affect authorization.
Tool contracts should also define failure responses. A Lambda or API should return structured information that lets the agent distinguish “resource not found,” “not authorized,” “temporary service failure,” and “business rule rejected.” A single free-text error forces the model to interpret operational state and can lead to inappropriate retries or user messaging.
Action-group ownership should be visible in production documentation. The team that owns the agent may not own the system being invoked. Runbooks should name the downstream service owner, escalation path, rate limits, and change process so a tool incident does not become an agent-team guessing exercise.
Action-group deprecation should also be deliberate. Removing a tool can change how the agent solves existing prompts, so releases should test whether the model falls back to another safe path or begins making worse choices. Capability removal is a behavior change, not merely cleanup.
Document that lifecycle explicitly.
Keep ownership and rollback documented.
Recorded.
