AgentCore Basics

Define and run a minimal agent via the managed harness and SDK/CLI.

This page is the smallest possible round trip through Amazon Bedrock AgentCore: write an entrypoint, deploy it as a runtime, and invoke it. Every other page in this section - Gateway tools, memory, observability - builds on top of this same loop, so it is worth getting comfortable with before adding anything else.

Amazon Bedrock AgentCore is a 2026 preview capability. The class names, decorators, and CLI subcommands below reflect AWS's publicly shown direction at the time of writing, but this is the fastest-moving surface in this whole cookbook - verify each name against current AWS documentation before you build on it.

Prerequisites

• Python: pip install boto3 bedrock-agentcore (an AWS-published SDK package for wrapping agent entrypoints; verify the current package name). TypeScript: npm install @aws-sdk/client-bedrock-agentcore for the data-plane invoke calls (Node.js 18+).
• An AgentCore CLI, likely installed via a starter-toolkit package (pip install bedrock-agentcore-starter-toolkit or similar) - see the CLI page in this section for what it does. Confirm the current install path before scripting around it.
• Credentials configured as usual (aws configure, environment variables, or a role) with permission to create and invoke AgentCore runtimes - the exact IAM actions are AgentCore-specific and should be pulled from current AWS documentation rather than assumed.
• A region where AgentCore is available at time of use - this is a newer capability with narrower regional coverage than long-established services like S3 or Bedrock model access.

Basic Examples

1. Write a Minimal Agent Entrypoint

Wrap a plain function as the thing AgentCore Runtime will invoke.

# --- Python (illustrative - verify class/decorator names against current AWS docs) ---
from bedrock_agentcore.runtime import BedrockAgentCoreApp
import boto3
 
app = BedrockAgentCoreApp()
brt = boto3.client("bedrock-runtime", region_name="us-east-1")
 
@app.entrypoint
def invoke(payload):
    prompt = payload.get("prompt", "Say hello.")
    resp = brt.converse(
        modelId="amazon.nova-lite-v1:0",
        messages=[{"role": "user", "content": [{"text": prompt}]}],
    )
    return {"reply": resp["output"]["message"]["content"][0]["text"]}
 
if __name__ == "__main__":
    app.run()  # starts a local server for testing before you deploy

• The entrypoint is ordinary code - here it just calls Bedrock's Converse API, but it could run any framework's agent loop instead.
• app.run() is described as starting a local dev server so you can exercise the entrypoint before deploying anything.
• Nothing about session isolation, scaling, or deployment lives in this file - that is the runtime's job once you deploy it.
• This snippet is CLI-only for the wrapper class name and decorator - no equivalent TypeScript agent-hosting SDK is assumed here; TypeScript is used below for the data-plane invoke side, which is the part with a published AWS SDK v3 client.

Related: The AgentCore Managed Harness: Model + Prompt + Tools - what belongs inside this entrypoint.

2. Deploy the Agent with the CLI

Package and register your entrypoint as a runtime AWS can invoke.

# --- AgentCore CLI (illustrative subcommands - verify against current AWS docs) ---
agentcore configure --entrypoint my_agent.py
agentcore launch

• Configuration is expected to be a one-time step per project - it points the tooling at your entrypoint file and sets build options.
• Launching is expected to build your code, create or update the AgentCore runtime resource, and return an ARN you invoke later.
• Treat both subcommand names as representative - the CLI page in this section covers the tool in more depth and repeats this caveat.
• A successful launch is a control-plane operation; it does not run your agent, it registers it so it can be run.

3. Invoke the Deployed Runtime

Call your hosted agent the same way you would call any AWS data-plane operation.

# --- Python (boto3) --- verify exact operation/param names at build time
import boto3, json
 
client = boto3.client("bedrock-agentcore", region_name="us-east-1")
resp = client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/my-agent",
    payload=json.dumps({"prompt": "Give me a fun fact."}).encode(),
)
print(json.loads(resp["response"].read()))

// --- TypeScript (AWS SDK v3) --- verify exact operation/param names at build time
import { BedrockAgentCoreClient, InvokeAgentRuntimeCommand } from "@aws-sdk/client-bedrock-agentcore";
 
const client = new BedrockAgentCoreClient({ region: "us-east-1" });
const resp = await client.send(new InvokeAgentRuntimeCommand({
  agentRuntimeArn: "arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/my-agent",
  payload: new TextEncoder().encode(JSON.stringify({ prompt: "Give me a fun fact." })),
}));
console.log(new TextDecoder().decode(resp.response as Uint8Array));

• The invoke call is a normal AWS request: build a client, send an input, read a response - the same mental model as any other SDK operation.
• The payload is opaque bytes as far as the runtime API is concerned; your entrypoint decides what shape of JSON it expects.
• The response is likewise a byte stream you decode and parse - do not assume a fixed schema beyond what your own entrypoint returns.
• This is a data-plane call distinct from the control-plane configure/launch step above - creating a runtime and invoking it are separate operations, as with Lambda's create-function vs invoke.

4. Pass Structured Input and Handle Errors

Send a richer payload and check for a failed invocation.

# --- Python (boto3) --- verify exact exception types at build time
import boto3, json
from botocore.exceptions import ClientError
 
client = boto3.client("bedrock-agentcore", region_name="us-east-1")
 
try:
    resp = client.invoke_agent_runtime(
        agentRuntimeArn="arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/my-agent",
        payload=json.dumps({"prompt": "List two AWS regions.", "userId": "u-42"}).encode(),
    )
    print(json.loads(resp["response"].read()))
except ClientError as e:
    print("Invocation failed:", e.response["Error"]["Code"])

// --- TypeScript (AWS SDK v3) --- verify exact exception types at build time
import { BedrockAgentCoreClient, InvokeAgentRuntimeCommand } from "@aws-sdk/client-bedrock-agentcore";
 
const client = new BedrockAgentCoreClient({ region: "us-east-1" });
 
try {
  const resp = await client.send(new InvokeAgentRuntimeCommand({
    agentRuntimeArn: "arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/my-agent",
    payload: new TextEncoder().encode(JSON.stringify({ prompt: "List two AWS regions.", userId: "u-42" })),
  }));
  console.log(new TextDecoder().decode(resp.response as Uint8Array));
} catch (err) {
  console.error("Invocation failed:", err);
}

• Any field beyond what your entrypoint reads (like userId here) is just part of your own payload contract, not an AgentCore-defined field.
• Wrap invocations the same way you would any AWS call - transient/throttling errors are plausible under load, same as other services.
• A failure here can mean the runtime itself errored, or that your entrypoint code raised - check your own logging (see the observability page) to tell them apart.
• Keep payloads reasonably small; large inputs belong in an S3 reference or a tool call, not stuffed into the invoke payload.

Intermediate Examples

5. Test the Entrypoint Locally Before Deploying

Exercise your code without touching AWS at all.

# --- Local dev loop (illustrative - verify current tooling) ---
python my_agent.py
# in another terminal:
curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Say hello."}'

• Running the entrypoint file directly is expected to start a local HTTP server that mimics the deployed invoke contract.
• Testing locally first catches obvious errors (bad imports, wrong model id) before a slower deploy-and-invoke cycle.
• The exact port and path shown are illustrative; confirm the current local-serving contract in AWS's AgentCore documentation.
• Nothing about this local loop involves IAM or billing - it only exercises your own function.

6. List Your Deployed Runtimes

Use the control-plane client to see what is registered.

# --- Python (boto3) --- control-plane client name/operation illustrative, verify at build time
import boto3
 
control = boto3.client("bedrock-agentcore-control", region_name="us-east-1")
for r in control.list_agent_runtimes().get("agentRuntimes", []):
    print(r.get("agentRuntimeArn"), "-", r.get("status"))

// --- TypeScript (AWS SDK v3) --- control-plane client name/operation illustrative, verify at build time
import { BedrockAgentCoreControlClient, ListAgentRuntimesCommand } from "@aws-sdk/client-bedrock-agentcore-control";
 
const control = new BedrockAgentCoreControlClient({ region: "us-east-1" });
const out = await control.send(new ListAgentRuntimesCommand({}));
for (const r of out.agentRuntimes ?? []) console.log(r.agentRuntimeArn, "-", r.status);

• Mirroring Bedrock's own split, expect a separate control-plane client for management operations like listing, describing, and deleting runtimes.
• A status field is a reasonable thing to expect (deploying, active, failed) but confirm the actual field names before scripting against them.
• Use this kind of call in CI or an ops script to confirm a deploy actually landed, rather than trusting the CLI's exit code alone.
• Treat the client and operation names in this example as the most likely shape, not a confirmed contract.

Related

• AgentCore's Managed Agent Runtime - what the runtime handles vs what your code owns.
• AgentCore CLI & Skills for Coding Assistants - the deploy tooling used above, in depth.
• Observability & Guardrails for Production Agents - seeing what an invocation actually did once it's live.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+). Amazon Bedrock AgentCore is a fast-moving 2026 preview capability - verify exact API/CLI surface against current AWS docs before relying on specific method names. NzA2MjAyfDIzMTFvaWdjfG9pLnNlZGl1Z2Vkb2M=