Minimal Blueprint

A bare-bones WhatsApp echo agent — the smallest runnable SMART (Social Messaging Agent Runtime Toolkit) project and the recommended starting point for building your own agent from scratch.

This blueprint wires the full SMART message path (inbound webhook, outbound notification, scheduler, and event Lambdas) to a trivial agent that echoes whatever the user sends. Everything works end to end, so you can replace the echo logic with your own agent and deploy immediately.

Rules for AI assistants

1. Read this file and SOCIALAGENT_GUIDE.md before changing the project; the guide covers tools, skills, scheduling, notifications and deploys.
2. Agent-side code (agent.py, src/) imports only socialagent_runtime, its own src/ modules and libraries in requirements.txt; handler Lambdas (handlers/) import socialagent and handlers/shared/. Do not mix the two.
3. This agent has no tools. If you add one that sends a WhatsApp message during a turn, wrap the entrypoint's agent call in socialagent_notify_context() and return its queue in SocialAgentResponse (see SOCIALAGENT_GUIDE.md); never call the notification Lambda directly from a tool.
4. Do not edit socialagent_runtime/: it is a vendored copy that socialagent runtime update replaces. Change behavior in your own code instead.
5. Hard-code no account IDs, ARNs, phone numbers or model IDs; configuration lives in socialagent.<env>.yaml.
6. Test locally with socialagent dev before deploying, and ask before socialagent deploy, socialagent destroy or anything that sends real messages.

Files and directories

Note: socialagent init also copies the vendored socialagent_runtime/ package into the project root. It is the Agent Runtime Package (notify, state, scheduler, messages, phone, config) your agent calls during a turn.

Extension points

• Agent logic — replace the echo body in agent.py's invoke function. Bring any agent framework (Strands, LangGraph, plain Bedrock calls); only agent.py is framework-specific.
• Tools and skills — this blueprint ships none. Add agent tools and skills under a src/ directory and wire them into agent.py, or copy a ready-made tool with socialagent recipe add <name> (e.g. rich-messages, voice-reply, generate-image).
• Scheduled messages — uncomment and implement the @app.on_schedule("<operation>") handler in handlers/scheduler.py for proactive/recurring outreach.
• External events — uncomment and implement the @app.on_event("<event>") handler in handlers/event.py to receive events from outside systems via API Gateway.
• Lambda-side helpers — add shared modules under handlers/shared/.
• Dependencies — add libraries to requirements.txt.

Run locally

From the scaffolded project directory:

uv pip install -r requirements.txt        # install dependencies (no pyproject.toml, so not uv sync)
uv run socialagent dev --entrypoint agent.py     # interactive local REPL (no deployed stack)

socialagent dev runs the agent loop locally and stubs out AWS-backed calls, so you can iterate on agent.py before deploying.