Local development

Toolchain

Tool Version Used for

Python

3.12+

Runtime and all Lambdas

uv

latest

Every Python dependency operation

pnpm

latest

CDK dependencies

Node.js

≥ 20

CDK CLI only

Docker

latest

AgentCore image builds

AWS CLI

v2

Deploys, log tailing, queue inspection

AWS SAM CLI

latest

Lambda build, local invoke, deploy

AWS CDK CLI

v2

Infrastructure deploy

Package-manager rules are hard constraints in this repository:

  • uv for agentcore/ and libs/ — never pip install or poetry

  • pnpm for cdk/ — never npm install

  • Lambda layer dependency lists are produced with uv pip compile pyproject.toml -o requirements.txt

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Repository setup

# Runtime dependencies
make install          # uv sync --directory agentcore

# CDK dependencies
cd cdk && pnpm install

Each Lambda and each library has its own pyproject.toml and its own virtual environment; run uv sync inside whichever directory you are working in.

Running the AgentCore runtime locally

export SECRET_ARN=arn:aws:secretsmanager:us-east-1:625663093496:secret:agentcore-secrets-XXXXXX
make dev              # uv run --directory agentcore python -m agentcore.main

Always python -m agentcore.main, never python agentcore/main.py. Running the file directly puts agentcore/ on sys.path[0], so agentcore/types/ shadows the standard-library types module and the import graph breaks.

Send a test invocation:

curl -X POST http://localhost:9000/invocations \
  -H 'Content-Type: application/json' \
  -d '{"workflow":"test","payload":{"prompt":"What is 2 + 2?"}}'

Valid AWS credentials are required — the runtime reads the secret from Secrets Manager and calls Bedrock through the ambient IAM identity. See AgentCore development.

Running Lambdas locally

Build once, then invoke a function with a sample event:

cd lambdas
sam build
sam local invoke MorpheusHubspotFunction \
  --event morpheus_hubspot/events/samples/contact_update.json

Sample payloads live in <function>/events/samples/, each with a README.md describing when to use them. For a scheduled handler, hand-craft the EventBridge envelope:

{"detail-type": "Hubspot.EmailClickReEngagement", "source": "morpheus.hubspot", "detail": {}}

sam local invoke still reaches real AWS for Secrets Manager, SQS, Bedrock, and the database, so treat every local run as production traffic against those systems.

Tests

Command Scope

make test

AgentCore runtime tests (uv run pytest agentcore/test/ -v)

cd lambdas && uv run pytest tests/ -v

Cross-function unit tests

cd lambdas && uv run pytest morpheus_hubspot/tests -v

morpheus-hubspot handler tests (re-engagement, dialer filters, Five9, lifecycle)

cd lambdas/enrichment_scraper && uv run pytest tests -v

SmartScout provider and auth tests

cd libs/morpheus-common && uv run pytest tests -v

Event model validation tests

cd libs/morpheus-data-layer && uv run pytest tests -v

Repository tests; tests/integration/ needs a reachable database

cd libs/pyb-hubspot && uv run pytest tests -v

HubSpot helper tests (mocked SDK)

cd cdk && pnpm test

CDK snapshot tests

Handler modules defer imports of Lambda-layer packages inside @lru_cache functions (_get_agent(), load_secrets()), so a test can import the module and patch at the function boundary without the layer installed. Preserve that pattern when adding agents.

More detail: Testing Lambdas.

Documentation

This component is AsciiDoc for Antora. To preview, add this repository as a content source in the central playbook and build there — there is no standalone playbook in this repository. See Writing these docs.

Conventions

Before changing code, read Engineering conventions; it mirrors AGENTS.md, the authoritative rule set for this repository.