Spec First design for the BedrockAgentFunctionResolver

[jeremycare]

Hi All!

In other projects where I need to implement an API with an OpenAPI, I tend to implement a spec-first design, where the code is generated/integrated with the OpenAPI Spec.

That provides some advantages:

• Type-safe
• Spec is always up to date

Since we can define the tools of an ActionGroup as an OpenAPI spec, I think it would be beneficial to be able to inject the spec and have the BedrockAgentFunctionResolver typed correctly.

Something like that:

import openapi from './openapi.json';
import { BedrockAgentFunctionResolver } from '@aws-lambda-powertools/event-handler/bedrock-agent';
import type { Context } from 'aws-lambda';

const resolver = new BedrockAgentFunctionResolver({ openapi });

resolver.tool(
  // this type would be injected properly from the OpenAPI spec
  async ({ city }) => {
    return {
      city,
      airportCode: 'XYZ',
    };
  },
  {
    operationId: 'getAirportCodeForCity',
  }
);

export const handler = async (event: unknown, context: Context) =>
  resolver.resolve(event, context);

I think this approach would make it much easier to ensure type-safety and consistency between the OpenAPI definition and the resolver implementation. Would you consider supporting this kind of spec-driven typing in BedrockAgentFunctionResolver?

[jeremycare]

Actually, I just realised the current BedrockAgentFunctionResolver does not handle the actionGroup defined with openapi spec. But only the ones defined with the functions.

When using function definitions:

{
    "messageVersion": "1.0",
    "function": "search",
    "parameters": [
        {
            "name": "query",
            "type": "string",
            "value": "SELECT ...;"
        }
    ],
    "sessionId": "...",
    "agent": {
        "name": "agent",
        "version": "DRAFT",
        "id": "...",
        "alias": "..."
    },
    "actionGroup": "action-group",
    "sessionAttributes": {},
    "promptSessionAttributes": {},
    "inputText": "INPUT"
}

When using openapi spec:

{
    "messageVersion": "1.0",
    "parameters": [
        {
            "name": "query",
            "type": "string",
            "value": "SELECT ...;"
        }
    ],
    "inputText": "..",
    "sessionId": "...",
    "agent": {
        "name": "agent",
        "version": "DRAFT",
        "id": "....",
        "alias": "...."
    },
    "actionGroup": "action-group",
    "sessionAttributes": {},
    "promptSessionAttributes": {},
    "httpMethod": "GET",
    "apiPath": "/search/{query}"
}

[dreamorosi]

Hi @jeremycare, as you noticed we only support the Bedrock Agents mechanism in which you specify the function details directly (aka this) but don't support the where OpenAPI is the source of truth (aka this other one).

Originally our plan was to support both, however since then AWS released AgentCore so it's unclear to us if there's still demand for Bedrock Agents in their current form.

With that said, we're currently working on adding a more general purpose Event Handler (#3500) that will support OpenAPI out of the box. Once that's completed, most of the logic for having a Bedrock Agents OpenAPI resolver should be in place.

At least for now I don't have a definite ETA for when that will be ready, but I think it'll be at least 1-2 more months from now.