Configuration

All runtime configuration is resolved once at startup by agentcore/config/loader.py. The result is an immutable AppConfig cached in a module global for the container’s lifetime.

Platform-wide configuration is in Configuration and secrets; this page covers only the runtime.

load_config()

def load_config() -> AppConfig:
    global _cached_config
    if _cached_config is not None:
        return _cached_config                      # 1. cache hit

    secret_arn = os.environ.get("SECRET_ARN")
    if not secret_arn:
        raise RuntimeError("SECRET_ARN environment variable is not set. …")   # 2. fail fast

    sm_client = boto3.client("secretsmanager", region_name="us-east-1")       # 3. fetch
    response = sm_client.get_secret_value(SecretId=secret_arn)
    secrets = _SecretsSchema.model_validate(json.loads(response["SecretString"]))  # 4. validate

    os.environ["OPENAI_API_KEY"] = secrets.OPENAI_API_KEY                    # 5. inject
    if secrets.CLAUDE_API_KEY:
        os.environ["ANTHROPIC_API_KEY"] = secrets.CLAUDE_API_KEY
    os.environ["HUBSPOT_CLIENT_ID"] = secrets.HUBSPOT_CLIENT_ID
    os.environ["HUBSPOT_CLIENT_SECRET"] = secrets.HUBSPOT_CLIENT_SECRET
    os.environ["HUBSPOT_REFRESH_TOKEN"] = secrets.HUBSPOT_REFRESH_TOKEN
    if secrets.TAVILY_API_KEY:
        os.environ["TAVILY_API_KEY"] = secrets.TAVILY_API_KEY

    _cached_config = AppConfig(...)                                          # 6. build + cache
    return _cached_config

Two things to note:

  • SECRET_ARN is mandatory. Its absence raises at import time, so a misconfiguration surfaces at container start rather than at the first invocation.

  • The region is hardcoded to us-east-1 for the Secrets Manager client, not read from AWS_REGION.

CLAUDE_API_KEY is injected under the name ANTHROPIC_API_KEY, which is what the Anthropic SDK looks for. It is unnecessary on Bedrock, where the IAM role authenticates.

Secret schema

_SecretsSchema — only these keys are read by the runtime; everything else in the shared secret is ignored.

Key Required Purpose

OPENAI_API_KEY

yes

Validated non-empty. Reserved for a future OpenAI provider.

HUBSPOT_CLIENT_ID

yes

Validated non-empty

HUBSPOT_CLIENT_SECRET

yes

Validated non-empty

HUBSPOT_REFRESH_TOKEN

yes

Validated non-empty

CLAUDE_API_KEY

no

Injected as ANTHROPIC_API_KEY when present

TAVILY_API_KEY

no

Injected when present

OPENAI_API_KEY is required and validated non-empty even though no OpenAI provider exists. A secret without it fails the container’s cold start. Populate it with a placeholder if you have no OpenAI account, or relax the schema.

A field_validator rejects whitespace-only values for the four required keys, so a blank string fails as loudly as a missing key.

AppConfig

class AppConfig(BaseModel):
    # credentials (also injected into os.environ)
    openai_api_key: str
    claude_api_key: str | None
    hubspot_client_id: str
    hubspot_client_secret: str
    hubspot_refresh_token: str
    tavily_api_key: str | None
    # provider defaults
    provider: str
    model_id: str
    agent_name: str
    system_prompt: str
    max_tokens: int
    max_turns: int

Agent modules read the credential fields from this object rather than from os.environ, and pass them explicitly into tool factories. See Tools.

Environment variables

Required

Variable Source

SECRET_ARN

Injected by the CDK stack when secretArn is set on the stack props

Injected by CDK

Variable Value

AWS_REGION

The stack’s region

LOG_GROUP_NAME

/aws/bedrock-agentcore/agents/agentcore

MEMORY_ID

CfnMemory.attrMemoryId — enables AgentCore Memory

Optional provider defaults

Read by load_config(), each with a code fallback:

Variable Default Effect

DEFAULT_AGENT_PROVIDER

claude

Selects the default model table entry

DEFAULT_MODEL_ID

anthropic.claude-3-5-sonnet-20241022-v2:0 (from PROVIDER_DEFAULT_MODEL["claude"])

AppConfig.model_id

DEFAULT_AGENT_NAME

AgentCore

Display name

DEFAULT_SYSTEM_PROMPT

You are a helpful, accurate, and concise AI assistant.

Fallback system prompt

DEFAULT_MAX_TOKENS

4096

AppConfig.max_tokens

DEFAULT_MAX_TURNS

10

AppConfig.max_turns

These defaults are currently unused by the registered workflows. Both agents carry their own explicit AgentConfig — dialler_agent pins AgentModelIds.CLAUDE_SONNET_4, 1000 tokens, 10 turns. `AppConfig’s provider defaults matter only to code that reads them, and nothing does today.

Note also that PROVIDER_DEFAULT_MODEL["claude"] lacks the us. prefix, so it would not resolve as a cross-region inference profile if it were used.

Read by constants.py

Constant Variable Default

LOG_GROUP_NAME

LOG_GROUP_NAME

/aws/bedrock-agentcore/agents/default

AGENT_MAX_TOKEN

MAX_TOKENS

4096

MEMORY_ID

MEMORY_ID

"" (empty disables memory)

DEFAULT_SYSTEM_PROMPT

—

hardcoded

DEFAULT_AGENT_NAME

—

AgentCore

Rotating credentials

The secret is cached in a module global for the container’s lifetime. A rotated value takes effect on the next cold start. Force one by redeploying, or by updating the runtime configuration so the platform recycles the container.

Adding a secret key

  1. Add the key to the Secrets Manager secret.

  2. Add the field to _SecretsSchema in agentcore/config/loader.py — optional unless the runtime genuinely cannot start without it.

  3. Inject it into os.environ only if a third-party SDK needs to auto-discover it.

  4. Add it to AppConfig and populate it in the _cached_config constructor.

  5. Pass it explicitly to whatever needs it, rather than having that code read os.environ.

  6. Document it in the shared secret.