Before we build anything, two ideas. First: an Amazon Bedrock AgentCore runtime is just a container that answers two HTTP routes — that is the whole contract. Second: with Alchemy, the agent and the AWS infrastructure that hosts it are one Effect program. This lesson sets up both, and what the rest of the course builds on them.
Amazon Bedrock AgentCore is AWS's managed platform for running AI agents in production — it is deliberately framework-agnostic and model-agnostic. You can bring Strands, LangGraph, CrewAI, LlamaIndex, or nothing at all, on any model, and AgentCore supplies the surrounding infrastructure: a serverless Runtime, a tool Gateway, managed Memory, Identity, Observability, and built-in tools.
The piece that hosts your agent is AgentCore Runtime. Despite the surrounding suite, the Runtime itself asks almost nothing of you: give me a container that speaks a tiny HTTP contract, and I will run it serverlessly, at scale, with the rest of the platform wired in. No SDK lock-in, no special base image, no agent framework required.
agentcore-samples/README.md
Here is the entire interface a container must implement to run on AgentCore Runtime. This is a real TypeScript sample from the AWS repo, reduced to its shape:
import http from "node:http";
http.createServer(async (req, res) => {
// 1. health check
if (req.url === "/ping") {
res.writeHead(200, { "Content-Type": "application/json" });
return res.end('{"status":"Healthy"}');
}
// 2. the agent turn
if (req.method === "POST" && req.url === "/invocations") {
const prompt = /* read JSON body */;
const result = await agent.invoke(prompt);
res.writeHead(200, { "Content-Type": "application/json" });
return res.end(JSON.stringify({ response: result }));
}
res.writeHead(404);
res.end();
}).listen(8080, "0.0.0.0"); // ← AgentCore calls you here| Route | Who calls it | Contract |
|---|---|---|
GET /ping | AgentCore health checks | Return 200 with {"status":"Healthy"} |
POST /invocations | Every agent call | Read the request body, run a turn, return JSON |
listen on :8080 | The platform | Bind 0.0.0.0:8080 inside the container |
That is the complete runtime contract. AgentCore Runtime is not "a place to put a Strands agent" — it is "a place to put an HTTP server on port 8080 that answers /ping and /invocations." The agent framework, the model, the language inside the container are all your choice. The sample above happens to use the Strands TS SDK; nothing requires it.
06-workshops/.../07-direct-code-deploy-typescript/app.ts
Most AgentCore material is Python — the samples are roughly five-to-one Python over TypeScript, and the TypeScript that exists is mostly frontends and CDK stacks. It would be easy to conclude AgentCore is "a Python thing." But the contract in §02 says otherwise: anything that can serve two HTTP routes on a port can be an AgentCore agent.
An Effect HttpApi can serve two routes in its sleep. So instead of a Python agent with TypeScript infrastructure bolted alongside, we can write the agent itself in Effect — and then, with Alchemy, describe its infrastructure in the same program. That is the bet this course makes.
The Runtime is a socket, not a framework. Read /invocations as "your function's HTTP front door." Everything we build — the model call, the tools, the memory — happens behind that door, in whatever shape we like. AgentCore only watches the door.
Alchemy is the second idea. It models cloud infrastructure as values inside an Effect program — a bucket, a Lambda, an IAM role, a container registry are all yield*-ed resources in the same Effect.gen you already write application logic in. Its own tagline is Infrastructure-as-Effects: cloud infrastructure and application logic as a single, type-safe Effect program.
Three properties matter for us, and all three come straight from being a normal Effect program:
alchemy-effect/README.md
The AgentCore samples ship infrastructure in three flavours: CloudFormation, Terraform, and AWS CDK. They all work. The difference is not capability — it is the seam between "infrastructure" and "the thing running on it."
| Approach | Language | Where the seam falls |
|---|---|---|
| CloudFormation | YAML | Templates submitted to a service; debug in the console. |
| Terraform | HCL | Its own language and state store, separate plan/apply. |
| AWS CDK | TypeScript | TS that synthesises CloudFormation; infra only — runtime lives elsewhere. |
| Alchemy | Effect | No seam. Infra and runtime are the same program; failures are typed errors. |
CDK is the closest — it is also TypeScript — but it describes infrastructure that is then handed to CloudFormation, and the agent code is a separate artifact it merely points at. Alchemy collapses that: the container the agent runs in is built by the same program that declares the Runtime that hosts it, and a failed CreateAgentRuntime surfaces as an Effect error in the deploy, not a rolled-back stack you inspect later.
Alchemy has no built-in AgentCore resource today, and no CloudFormation escape hatch — its resources are hand-authored against the AWS API. So this course ships an AgentCore.Runtime (plus Gateway, Memory) resource as given library code; you consume it like any other Alchemy resource, and one appendix opens the hood on how it is built. The control-plane API it wraps is also alpha — we pin versions and date each lesson.
The hero of this course is an Effect-docs agent — an agent that answers questions about this very course by searching its explainers. It exists to exercise every AgentCore capability with one coherent story:
You will run it locally first (a stub model, no AWS credentials), deploy it for real at lesson 05, then layer on tools, memory, and tracing — each a few lines added to the same Effect program. The whole course is a single effect@4 codebase; we use Bedrock's Converse API directly (through Alchemy's AWS SDK) rather than a separate AI library, so there is exactly one Effect to learn.
You should now be able to say, in one breath, what AgentCore Runtime requires (a container serving /ping + /invocations on :8080) and what makes Alchemy different (the agent and its infrastructure are one typed Effect program). Lesson 02 turns the §02 contract into a real Effect HttpApi you can curl.