Action Groups: OpenAPI Schemas, Function Schemas and Lambda Executors

An action group is a bundle of related operations the agent may call. It has two halves that you always configure together: a definition (what the operations are called, what parameters they take, what they are for) and an executor (what actually runs when the agent picks one). The definition is what the model sees; the executor is what your account runs.

Two ways to define the operations

OpenAPI schema. You supply an OpenAPI 3.0 document, either inline via apiSchema.payload or from S3 via apiSchema.s3. Each path plus HTTP method becomes one callable operation. This is the right choice when the actions mirror an API you already have — you can often reuse the existing spec — and when you need rich typed request bodies and response schemas. The description on each operation and each parameter is not documentation; it is prompt text, and it is the main lever you have over tool selection.

Function detail definition. You supply a functionSchema: a list of functions, each with a name, a description and a flat map of parameters with type, description and required. There is no HTTP shape at all. This is simpler, produces a smaller prompt, and is the better choice for actions that were never an API — "escalate_to_human", "cancel_booking". Function definitions also support requireConfirmation, which makes the agent pause and ask the user to confirm before that function runs.

You pick one per action group. You cannot mix an OpenAPI schema and a function schema in the same action group, and the shape you choose changes the Lambda event and the response format you must return.

The executor

Set actionGroupExecutor.lambda to a function ARN and Bedrock invokes it synchronously. The event contains messageVersion, an agent block, inputText, sessionId, actionGroup, the resolved parameters, and both sessionAttributes and promptSessionAttributes. For OpenAPI groups you also get apiPath, httpMethod and requestBody, and you must return response.responseBody["application/json"].body as a string. For function groups you get function and return response.functionResponse.responseBody.TEXT.body, optionally with responseState set to REPROMPT to hand the model a corrective message, or FAILURE to signal an error.

Two operational details bite people. First, the Lambda needs a resource policy allowing bedrock.amazonaws.com to invoke it, scoped by SourceArn to the agent — the agent's execution role is not enough on its own. Second, the response payload is size-capped, so a tool that returns a large result set must paginate, filter or write to S3 and return a pointer instead of dumping everything into the model's context.

The parent action groups

Two built-in groups have no schema and no executor, only a parentActionGroupSignature. AMAZON.UserInput lets the agent ask a clarifying question instead of guessing at a missing parameter — without it, an agent short of a required value will often hallucinate one. AMAZON.CodeInterpreter gives the agent a sandbox for generating and running code over uploaded files.

An action group is also not a knowledge base. If the agent needs to read unstructured documents, associate a knowledge base and let retrieval happen; an action group is for effects and for structured lookups against systems of record.