Feature request: add support for AppConfig Agent in Parameters

[dreamorosi]

Use case

As a customer I want to use the Parameters utility to fetch configuration objects from AppConfig using the AWS AppConfig Agent which runs as Lambda extension inside my execution environment.

Solution/User Experience

Similarly to what customers can do today with the getAppConfig helper¹, customers should be able to easily fetch a configuration object using a helper function like this:

import { getConfig } from '@aws-lambda-powertools/parameters/appconfig-agent';

// Retrieve a configuration
const config = await getConfig('my-configuration', {
  environment: 'my-env',
  application: 'my-app',
  transform: 'json'
});

export const handler = async () => {
  console.log(config);
};

Note: the import has two differences from the existing one: 1/ function name becomes getConfig, 2/ the sub-path export becomes /parameters/appconfig-agent.

Since caching is handled by the extension and there's no AWS SDK client to tune, we will neither implement nor offer a corresponding provider class to AppConfigProvider². This allows us to create a lean implementation that always fetches the configuration object from the extension's endpoint, transforms it, and returns it to the caller.

Similarly, since caching is handled entirely by the AppConfig Agent Lambda extension, the getConfig helper function will not support the maxAge³ and forceFetch⁴ options. The transform⁵ parameter will still be supported, together with the current formats.

Customers using the getConfig helper function will be able to configure both caching and pre-fetching by using two environment variables exposed by the AppConfig Agent:

• AWS_APPCONFIG_EXTENSION_PREFETCH_LIST - Tells the extension to fetch config during INIT (before your handler runs), reducing cold-start latency. Value is the path to your config, e.g. /applications/my_app/environments/my_env/configurations/my_config.
• AWS_APPCONFIG_EXTENSION_POLL_TIMEOUT_MILLIS (default 3000) - Max time the extension waits for an AppConfig response during a poll. If it times out, the cached value is used.

So for example, if you set:

AWS_APPCONFIG_EXTENSION_POLL_INTERVAL_SECONDS=120
AWS_APPCONFIG_EXTENSION_PREFETCH_LIST=/applications/myapp/environments/prod/configurations/feature-flags

The extension will prefetch during cold start and then check for updates at most every 2 minutes on subsequent invocations.

It's important to note that the prefetch list is purely an optimization for cold starts in that it tells the extension to start fetching before your handler runs. At runtime, your function can request any configuration by calling the local HTTP endpoint:
GET http://localhost:2772/applications/{app}/environments/{env}/configurations/{config}.

If the requested configuration isn't already in the cache (because it wasn't prefetched), the extension will call AppConfig on the spot, cache the result, and return it to your function. Subsequent calls for the same configuration will be served from cache (subject to the poll interval for freshness).

So the prefetch list doesn't limit what you can access — it only controls what gets pre-warmed into the cache during INIT. Any configuration your IAM permissions allow can be fetched on-demand at any point during invocation.

Prefetching is particularly interesting for Powertools customers as it unlocks a new level of optimization not available with the current AppConfigProvider-based approach, specifically allowing parallelism during cold start.

Timeline comparison

With prefetch (AWS_APPCONFIG_EXTENSION_PREFETCH_LIST):

|-- Extension INIT --|
|   prefetch starts → AppConfig network call  |
|                                             |
|-- Runtime INIT (in parallel) ---------------|
|   module loading, top-level code...         |
|                                             |
|-- Handler invoked --------------------------|
|   GET localhost:2772 → already cached ✓     |

The extension begins fetching from AppConfig concurrently with your Node.js runtime initializing (parsing modules, running top-level code). By the time your code asks for the config, it's likely already in the cache.

Fetching in top-level code (no prefetch):

|-- Extension INIT --|
|   (no prefetch)    |
|                    |
|-- Runtime INIT ----|------------------------------|
|   module loading...                               |
|   await fetch("http://localhost:2772/...") -----> | calls AppConfig (blocking)
|   ...waits...                                     |
|   config received ←                               |
|                                                   |
|-- Handler invoked --------------------------------|

Your top-level await hits the extension, which has nothing cached, so it makes a synchronous (from your perspective) call to AppConfig. Your INIT blocks on the full network round-trip.

Practical impact

• Prefetch overlaps the AppConfig network latency with your module/dependency loading — effectively "free" if your module init takes longer than the AppConfig call.
• Top-level fetch adds the AppConfig latency on top of your module loading time.

For a typical Node.js function with several dependencies (SDK, ORM, etc.), prefetch can shave hundreds of milliseconds off cold starts because the network call happens while Node is busy parsing and loading your node_modules.

When the difference is negligible

• If your function has minimal dependencies (fast module load), the prefetch may not have finished by the time your code runs — in which case the extension blocks until the in-flight request completes, similar to a top-level fetch.
• On warm invocations, both behave identically (served from cache).

A note on testing: the getConfig helper function should be able to detect when it's not running in AWS Lambda and either become a no-op or return a fixed value. This is helpful for testing and local environments.

As part of the scoping for this issue, also check the benchmark analysis in #3754.

Alternative solutions

Since the internal implementation and mechanics of retrieving configurations is more similar to the recently released metadata feature than to the existing AWS SDK client-based approach we have decided to forego the existing BaseProvider approach used in Parameters.

While we considered using the same pattern in the name of consistency, we realized that following the same structure would've created a lot of indirection and boilerplate code which would've ended up in customers bundles.

Acknowledgment

• This feature request meets Powertools for AWS Lambda (TypeScript) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

Future readers

Please react with 👍 and your use case to help us understand customer demand.

Footnotes

1. getAppConfig ↩

2. AppConfigProvider ↩

3. Adjusting cache TTL ↩

4. Always fetching the latest ↩

5. Deserializing values with transform parameter ↩