Configuration and secrets

Configuration is split deliberately:

Secrets — credentials only. One Secrets Manager secret, agentcore-configs, read once per container and cached.
Environment variables — infrastructure wiring only: queue URLs, ARNs, tenant id, batch sizes, log level. Set by the SAM template or the CDK stack.

Agent configuration — model id, system prompt, provider, token limits — is never an environment variable and never lives in CDK or SAM. It is code, in agents/ modules and AgentConfig objects.

The shared secret

Secrets Manager secret name agentcore-configs (created by the SAM template as AgentcoreSecret, populated manually after the first deploy). It is a flat JSON object; each consumer maps only the keys it needs and ignores the rest.

Key Consumers Purpose

Key	Consumers	Purpose
`DATABASE_URL`	all Lambdas	PostgreSQL connection string with the `postgresql://` scheme; the data layer always connects through psycopg2. Use the Supabase Transaction mode pooler URL (port 6543) — see pooling.
`SMARTSCOUT_USERNAME`, `SMARTSCOUT_PASSWORD`	scraper	SmartScout account credentials used to obtain a session token.
`SMARTSCOUT_TOKEN`, `SMARTSCOUT_TOKEN_EXPIRES_AT`	scraper	Cached SmartScout session token. Written back to the secret by the scraper’s auth module — this is why the scraper has `secretsmanager:PutSecretValue`.
`HUBSPOT_PRIVATE_APP_TOKEN`	morpheus-hubspot	Preferred HubSpot auth. A `pat-…` Private App token; no refresh needed.
`HUBSPOT_CLIENT_ID`, `HUBSPOT_CLIENT_SECRET`, `HUBSPOT_REFRESH_TOKEN`	morpheus-hubspot, scorer, agentcore	HubSpot OAuth fallback, and the credentials the HubSpot MCP tool needs.
`HUBSPOT_ENVIRONMENT`	morpheus-hubspot	`production` or `preview` — selects the call-disposition outcome GUID set.
`TAVILY_API_KEY`	scorer, agentcore	Tavily Remote MCP web-search key used by the enrichment agent.
`OPENAI_API_KEY`	agentcore	Required by the runtime’s secret schema. Reserved for a future OpenAI provider.
`ANTHROPIC_API_KEY` (stored as `CLAUDE_API_KEY`)	agentcore	Optional. Not needed on Bedrock — the IAM role provides authentication.
`TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`	phone-agent	Twilio Lookup v2 line-type intelligence.
`SLACK_BOT_TOKEN`	phone-agent	Slack bot token for task reminders, DMs, and user lookup. Empty disables Slack work.
`BIGQUERY_CREDENTIALS`	scraper, morpheus-hubspot, phone-agent	Google service-account JSON, as a string. Empty makes every BigQuery-backed handler log a warning and return.
`NOOKS_API_KEY`, `NOOKS_DEFAULT_SEQUENCE_ID`, `NOOKS_DEFAULT_MAILBOX_ID`	morpheus-hubspot	Optional. Nooks Sequencing API, used by the dialer-call-ended sync.
`FILES_COM_API_KEY`	morpheus-hubspot	Files.com key used to download Five9 call-log CSVs.

DATABASE_URL

all Lambdas

PostgreSQL connection string with the postgresql:// scheme; the data layer always connects through psycopg2. Use the Supabase Transaction mode pooler URL (port 6543) — see pooling.

SMARTSCOUT_USERNAME, SMARTSCOUT_PASSWORD

scraper

SmartScout account credentials used to obtain a session token.

SMARTSCOUT_TOKEN, SMARTSCOUT_TOKEN_EXPIRES_AT

scraper

Cached SmartScout session token. Written back to the secret by the scraper’s auth module — this is why the scraper has secretsmanager:PutSecretValue.

HUBSPOT_PRIVATE_APP_TOKEN

morpheus-hubspot

Preferred HubSpot auth. A pat-… Private App token; no refresh needed.

HUBSPOT_CLIENT_ID, HUBSPOT_CLIENT_SECRET, HUBSPOT_REFRESH_TOKEN

morpheus-hubspot, scorer, agentcore

HubSpot OAuth fallback, and the credentials the HubSpot MCP tool needs.

HUBSPOT_ENVIRONMENT

morpheus-hubspot

production or preview — selects the call-disposition outcome GUID set.

TAVILY_API_KEY

scorer, agentcore

Tavily Remote MCP web-search key used by the enrichment agent.

OPENAI_API_KEY

agentcore

Required by the runtime’s secret schema. Reserved for a future OpenAI provider.

ANTHROPIC_API_KEY (stored as CLAUDE_API_KEY)

agentcore

Optional. Not needed on Bedrock — the IAM role provides authentication.

TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN

phone-agent

Twilio Lookup v2 line-type intelligence.

SLACK_BOT_TOKEN

phone-agent

Slack bot token for task reminders, DMs, and user lookup. Empty disables Slack work.

BIGQUERY_CREDENTIALS

scraper, morpheus-hubspot, phone-agent

Google service-account JSON, as a string. Empty makes every BigQuery-backed handler log a warning and return.

NOOKS_API_KEY, NOOKS_DEFAULT_SEQUENCE_ID, NOOKS_DEFAULT_MAILBOX_ID

morpheus-hubspot

Optional. Nooks Sequencing API, used by the dialer-call-ended sync.

FILES_COM_API_KEY

morpheus-hubspot

Files.com key used to download Five9 call-log CSVs.

Containers cache the secret for their lifetime (@lru_cache in Lambdas, a module global in the runtime). A rotated value takes effect on the next cold start, not immediately. Force a cold start by updating the function configuration or redeploying.

Populating the secret

aws secretsmanager put-secret-value \
  --secret-id agentcore-configs \
  --region us-east-1 \
  --secret-string '{
    "DATABASE_URL": "postgresql://…:6543/postgres",
    "HUBSPOT_PRIVATE_APP_TOKEN": "pat-na1-…",
    "HUBSPOT_CLIENT_ID": "…",
    "HUBSPOT_CLIENT_SECRET": "…",
    "HUBSPOT_REFRESH_TOKEN": "…",
    "TAVILY_API_KEY": "tvly-…",
    "OPENAI_API_KEY": "sk-…",
    "TWILIO_ACCOUNT_SID": "AC…",
    "TWILIO_AUTH_TOKEN": "…",
    "SLACK_BOT_TOKEN": "xoxb-…",
    "BIGQUERY_CREDENTIALS": "{\"type\":\"service_account\", …}"
  }'

Never commit a populated secret, a .env file, or a service-account JSON.

Lambda environment variables

Global defaults from Globals.Function.Environment in lambdas/template.yaml:

Variable Default Purpose

Variable	Default	Purpose
`LOG_LEVEL`	`INFO` (stack parameter `LogLevel`)	Root logger level, applied by each function’s `utils/logging.py`.
`SENTRY_DSN`	`""` (empty)	Empty disables Sentry entirely. See Observability.
`SENTRY_ENVIRONMENT`	`prod`	Environment tag on Sentry events.

LOG_LEVEL

INFO (stack parameter LogLevel)

Root logger level, applied by each function’s utils/logging.py.

SENTRY_DSN

"" (empty)

Empty disables Sentry entirely. See Observability.

SENTRY_ENVIRONMENT

prod

Environment tag on Sentry events.

Per function:

Table 1. enrichment-scraper
Variable	Value
`SQS_QUEUE_URL`	`EnrichmentPipelineQueue` URL
`AGENTCORE_SECRET_ARN`	ARN of `agentcore-configs`
`SMARTSCOUT_BASE_URL`	`https://smartscoutapi-east.azurewebsites.net`
`SUBSCRIPTION_ID`	`b191a905-5d19-4fa0-941b-d8eb81c0c477`

Additional Settings fields with code defaults (override via environment if needed): SMARTSCOUT_MARKETPLACE (US), ICP_REVENUE_MIN (100000), ICP_REVENUE_MAX (1000000), ICP_CATEGORIES (empty, comma-separated), MAX_PAGES_PER_RUN (1), PAGE_SIZE (10), BIGQUERY_CONTACT_SYNC_BATCH_SIZE (1000).

ICP_REVENUE_MIN/MAX are annual. The provider filter divides both by 12 to get the monthly bounds SmartScout expects. The validator rejects min >= max at import time, so a bad value fails the cold start loudly.

Table 2. enrichment-scorer
Variable	Value
`AGENTCORE_SECRET_ARN`	ARN of `agentcore-configs`
`SUBSCRIPTION_ID`	`b191a905-5d19-4fa0-941b-d8eb81c0c477` — must match the scraper
`CRM_SYNC_QUEUE_URL`	`CrmSyncQueue` URL. Empty disables CRM publishing (DB writes still happen).

Table 3. morpheus-hubspot
Variable	Value
`AGENTCORE_SECRET_ARN`	ARN of `agentcore-configs`
`SUBSCRIPTION_ID`	`b191a905-5d19-4fa0-941b-d8eb81c0c477` — events whose `subscription_id` differs are rejected
`CONTACT_HUBSPOT_RESOLVE_BATCH_SIZE`	`25` in the template (code default `100`) — rows per `Contact.ResolveHubSpotIds` run when the event omits `batch_limit`

Additional Settings fields with code defaults, overridable via environment: HUBSPOT_TASK_POLL_BATCH_SIZE (100), BIGQUERY_ENGAGEMENT_SYNC_BATCH_SIZE (1000), FIVE9_CALL_SYNC_BATCH_SIZE (500).

Table 4. email-agent
Variable	Value
`AGENTCORE_SECRET_ARN`	ARN of `agentcore-configs`

email-agent deliberately has no SUBSCRIPTION_ID. It is multi-tenant safe by deriving tenant scope from the loaded EmailCampaignTarget row. See tenant safety.

Table 5. phone-agent
Variable	Value
`AGENTCORE_SECRET_ARN`	ARN of `agentcore-configs`
`SUBSCRIPTION_ID`	`b191a905-5d19-4fa0-941b-d8eb81c0c477`
`CRM_SYNC_QUEUE_URL`	`CrmSyncQueue` URL
`EMAIL_AGENT_QUEUE_URL`	`EmailAgentQueue` URL — used by stage-1 task escalation
`PHONE_AGENT_BATCH_SIZE`	`25` — `target_phone_numbers` rows per Twilio run
`SALES_SLACK_CHANNEL_ID`	`sales-tasks`

AgentCore runtime environment variables

Injected by the CDK stack into CfnRuntime.environmentVariables:

Variable Value

Variable	Value
`AWS_REGION`	Stack region
`LOG_GROUP_NAME`	`/aws/bedrock-agentcore/agents/agentcore`
`MEMORY_ID`	Memory resource id from `CfnMemory`
`SECRET_ARN`	Secrets Manager ARN, only when `secretArn` is set on the stack props

AWS_REGION

Stack region

LOG_GROUP_NAME

/aws/bedrock-agentcore/agents/agentcore

MEMORY_ID

Memory resource id from CfnMemory

SECRET_ARN

Secrets Manager ARN, only when secretArn is set on the stack props

Optional runtime defaults read by agentcore/config/loader.py, all with code defaults: DEFAULT_AGENT_PROVIDER (claude), DEFAULT_MODEL_ID, DEFAULT_AGENT_NAME (AgentCore), DEFAULT_SYSTEM_PROMPT, DEFAULT_MAX_TOKENS (4096), DEFAULT_MAX_TURNS (10), MAX_TOKENS (used by constants.AGENT_MAX_TOKEN).

SECRET_ARN is mandatory — load_config() raises RuntimeError at import if it is absent. See runtime configuration.

Configuration held in the database

Some state is neither a secret nor an environment variable — it is a row in the configs table, so it survives cold starts and can be changed without a deploy.

configs.key Meaning

`configs.key`	Meaning
`enrichment.amazon.disabled`	`"true"` (case-insensitive) suspends Amazon discovery. Any other value, or absent, means active.
`enrichment.amazon.next_start_row`	Row offset where the next scheduled discovery run begins. `0` restarts from the top.
`bigquery_engagement_sync_watermark`	Last `lastupdated` timestamp consumed from the BigQuery engagements export.
`bq_contact_sync_watermark`	Last `updatedat` timestamp consumed from the BigQuery contacts export.
`five9_call_sync_watermark`	Last processed Files.com file modification time for Five9 CSVs.
`dialer_follow_up_rep_rr:<subscriptionId>`	Round-robin cursor for sales-rep assignment.

enrichment.amazon.disabled

"true" (case-insensitive) suspends Amazon discovery. Any other value, or absent, means active.

enrichment.amazon.next_start_row

Row offset where the next scheduled discovery run begins. 0 restarts from the top.

bigquery_engagement_sync_watermark

Last lastupdated timestamp consumed from the BigQuery engagements export.

bq_contact_sync_watermark

Last updatedat timestamp consumed from the BigQuery contacts export.

five9_call_sync_watermark

Last processed Files.com file modification time for Five9 CSVs.

dialer_follow_up_rep_rr:<subscriptionId>

Round-robin cursor for sales-rep assignment.

Full detail: Runtime state in configs.