AgentCore Runtime deploys a container-packaged AI agent on AWS Bedrock AgentCore. You supply your agent code as a container image, choose a communication protocol (HTTP, MCP, A2A, or AGUI), and Stacktape provisions the managed runtime — with optional connections to persistent memory, a tool gateway, a browser sandbox, and a code interpreter.
When to use
Use AgentCore Runtime when you're building an AI agent that needs managed infrastructure on AWS. You configure protocol, endpoints, lifecycle, and tool attachments declaratively — Stacktape provisions the runtime and wires everything together.
Good fits:
- Multi-turn AI agents that maintain state across requests and need session-level lifecycle control (idle timeouts, max lifetime).
- Tool-using agents that need access to a managed browser, code interpreter, or persistent memory without provisioning those services yourself.
- MCP or A2A agents where you want first-class protocol support rather than building your own protocol handling on top of HTTP.
- Teams standardizing on Bedrock who want their agent infrastructure managed alongside other Stacktape resources in a single stack.
When NOT to use
- Simple LLM API wrappers — if your service calls a model API and returns the response, a Lambda function or web service is simpler and cheaper.
- Non-AI container workloads — use a web service, private service, or multi-container workload instead. AgentCore Runtime provides protocol selection and tool-attachment properties that are unnecessary for general-purpose services.
- Latency-sensitive edge inference — consider an edge function with a lightweight model or API call instead.
Basic example
A minimal AgentCore Runtime using the HTTP protocol:
The AgentCoreRuntime resource configures a container-packaged agent runtime with protocol, endpoint, lifecycle, and tool-attachment properties. The config declares a chat endpoint using the HTTP protocol. This example uses DockerfilePackaging with buildContextPath: './agent', so Stacktape builds the runtime image with dockerfile packaging.
Examples
Agent with persistent memory and lifecycle
An agent that uses AgentCore Memory for cross-session context and sets session lifecycle limits. The useMemory value must match the resource name in the returned resources object — in this case agentMemory.
In this example, idleTimeoutSeconds is set to 300 and maxLifetimeSeconds to 7200 — these are example values; choose durations appropriate for your agent's session patterns. The memory resource keeps raw events for eventRetentionDays days (30 in this example, which is also the default).
Agent with tools, authentication, and resource access
A more complete agent that attaches a gateway (no tools configured in this example — see AgentCore Gateway), browser, and code interpreter, protects its endpoint with JWT authentication, and accesses a DynamoDB table via connectTo:
In this example, idleTimeoutSeconds is set to 1800 and maxLifetimeSeconds to 14400 — these are example values; choose durations appropriate for your agent's session patterns. For documented target resource types, connectTo grants IAM permissions and uses the STP_[RESOURCE_NAME]_[PARAM] naming pattern described in Connecting resources. For a DynamoDB table named conversations, the documented parameters include NAME, ARN, and STREAM_ARN. The supportedVersions on the gateway is an optional string array — see AgentCore Gateway for gateway-specific configuration. The authorizer property configures JWT authorizer settings: discoveryUrl (required) points to an OIDC discovery endpoint, while allowedAudience, allowedClients, and allowedScopes are optional string arrays that filter incoming tokens.
Protocols
AgentCore Runtime supports four communication protocols, set via the protocol property:
| Protocol | Description |
|---|---|
HTTP | Standard HTTP request/response. Works with any HTTP client or framework. |
MCP | Model Context Protocol. Standardized protocol for tool-calling agents that follow the MCP specification. |
A2A | Agent-to-Agent protocol. For agents that communicate with other agents using a structured agent protocol. |
AGUI | Agent GUI protocol. Choose this value when your container implements the AGUI specification. |
Use HTTP for a conventional request/response endpoint. Use MCP, A2A, or AGUI only when your agent implements that specific protocol. All four values are valid for the protocol property: 'HTTP', 'MCP', 'A2A', and 'AGUI'.
Endpoints
Define the API endpoints your agent runtime exposes with the endpoints property. Each endpoint can be a simple string (the endpoint name) or an object with additional configuration. If you omit endpoints, Stacktape creates one endpoint named default. If you configure the property, provide at least one endpoint and give every endpoint a unique name.
The resource's endpointName and endpointArn references point to the endpoint named default when the list contains one. Otherwise, they point to the first configured endpoint. Put the endpoint you want other resources to use first, or name it default; the remaining endpoints are still created but are not exposed through those shorthand resource parameters.
When using the object form, you can set:
name— The endpoint identifier (required).description— Human-readable description of what the endpoint does.runtimeVersion— Pin a specific runtime version for this endpoint.
Use named endpoints when your agent exposes multiple capabilities (e.g., a chat endpoint for conversations and an analyze endpoint for document processing). Use the object form when you need to attach metadata or pin a runtime version.
Tool integrations
AgentCore Runtime can connect to managed tools that extend your agent's capabilities. Each tool is a separate Stacktape resource that you reference by name:
| Property | Resource type | What it provides |
|---|---|---|
useMemory | AgentCore Memory | Memory store with optional eventRetentionDays retention |
useGateway | AgentCore Gateway | MCP-style tool gateway with governed tool definitions |
useBrowser | AgentCore Browser | Sandboxed browser for web research |
useCodeInterpreter | AgentCore Code Interpreter | Sandboxed code execution environment |
You can attach all four simultaneously. Each property is a string that references a same-stack AgentCore resource by name. The value must match the resource name in the returned resources object.
useMemory— attach when your agent needs retained context across sessions (conversation history, user preferences). Skip for stateless, single-turn request/response agents.useGateway— attach when tool definitions need to be managed and governed separately from the agent code. Skip when your agent handles tool calls internally.useBrowser— attach only when the agent needs to browse external web pages. Adds a managed browser sandbox, which increases the resource footprint.useCodeInterpreter— attach only when the agent needs to execute user-provided or generated code. Adds a sandboxed execution environment.
To access resource attributes from other parts of your config, use the $ResourceParam directive.
In the example above, the gateway uses authorizer: { type: 'none' } to keep the example short; protect a real gateway with a JWT authorizer. supportedVersions: ['2025-03-26'] is an optional string array. No tools are configured on the gateway in this example — see AgentCore Gateway for defining tool entries (each requires a toolSchema). See also AgentCore Browser, AgentCore Code Interpreter, and AgentCore Memory.
Lifecycle
Control how long agent runtime sessions live with the lifecycle property. Use these settings to manage session duration and control costs.
maxLifetimeSeconds— Maximum lifetime of a runtime session, in seconds. After this time, the session ends even while it is active. AWS defaults to 8 hours.idleTimeoutSeconds— How long an idle session stays alive before it ends, in seconds. AWS defaults to 15 minutes.
In this example, idleTimeoutSeconds is set to 300 and maxLifetimeSeconds to 3600 — these are example values; choose durations appropriate for your agent's session patterns. Both properties accept a numeric value. For cost-sensitive workloads, consider a shorter idleTimeoutSeconds to reclaim idle sessions sooner. Use a longer maxLifetimeSeconds for agents that maintain important in-memory state across a multi-step conversation.
Authentication
Protect your agent endpoints with JWT-based authorization using the authorizer property. The discoveryUrl is required and points to your identity provider's OpenID Connect discovery document. You can optionally restrict access by audience, client ID, or scope.
| Property | Purpose |
|---|---|
discoveryUrl | OIDC discovery endpoint URL (required) |
allowedAudience | Valid aud claim values |
allowedClients | Valid client IDs in the token |
allowedScopes | Required scopes the token must contain |
Configure an authorizer for any agent endpoint exposed to the public internet. You may skip it temporarily for private prototypes or agents protected by another trusted entry point (e.g., behind an internal API gateway). JWT auth requires an OIDC provider (such as Amazon Cognito or Auth0) and token management by the caller. The discoveryUrl is the only required field — allowedAudience, allowedClients, and allowedScopes are optional string array filters you can layer on top to further restrict which tokens are accepted.
Connecting to other resources
AgentCore Runtime accepts connectTo through ResourceAccessProps. For supported target resource types, connectTo grants IAM permissions and provides STP_[RESOURCE_NAME]_[PARAM] connection values as documented in Connecting resources.
In this example, the agent gets read/write access to the S3 bucket and DynamoDB table. The connectTo property provides connection values following the STP_[RESOURCE_NAME]_[PARAM] pattern — for example, STP_KNOWLEDGE_BASE_NAME and STP_CONVERSATION_LOG_NAME. See Connecting resources for the full reference by resource type.
For AWS services not covered by connectTo, use iamRoleStatements to add raw IAM policy statements:
This example grants permission to invoke any Anthropic Claude foundation model via the Bedrock API. Adjust the Action and Resource values to match the AWS services your agent needs.
Packaging
AgentCore Runtime uses container packaging, the same types available to other container workloads. Four packaging types are supported:
| Type | Class | When to use |
|---|---|---|
js-bundle | JsBundleImagePackaging | A JavaScript or TypeScript agent with one entry file. |
buildpack | BuildpackImagePackaging | Build from source without a Dockerfile. The language and start command are detected. Suits Python agents. |
dockerfile | DockerfilePackaging | Full control over the container environment. Use when you need specific system dependencies or a custom base image. |
prebuilt-image | PrebuiltImagePackaging | Reference an existing image from any registry. Skips the build step. |
Most teams use DockerfilePackaging for full control or BuildpackImagePackaging to build without a Dockerfile. With PrebuiltImagePackaging, provide a reference to an existing public image or a private image with repositoryCredentialsSecretArn when credentials are needed. This page shows DockerfilePackaging because agent containers commonly need runtime-specific dependencies. See container packaging for all four types.
Environment variables
Pass configuration to your agent container with the environment property. Use the $Secret directive for sensitive values.
Each entry needs a name and a value. Values are strings, numbers, or booleans (numbers and booleans are converted to strings). For supported target resource types, connectTo uses the documented STP_[RESOURCE_NAME]_[PARAM] naming pattern for connection values. Use environment for values you want to pass explicitly to the runtime. See Connecting resources for the full reference.
Request headers
The requestHeaders property accepts an array of header name strings for the AgentCore Runtime:
Use requestHeaders when the runtime needs named request headers such as tenant or trace identifiers. The property accepts an optional array of header name strings.
AgentCore Runtime FAQ
What protocols does AgentCore Runtime support?
AgentCore Runtime supports four protocols: HTTP (standard request/response), MCP (Model Context Protocol for tool-calling agents), A2A (Agent-to-Agent communication), and AGUI (Agent GUI for interactive UIs). Set the protocol via the protocol property. Choose MCP or A2A when your agent specifically implements those protocol specifications; use HTTP for general-purpose agent endpoints.
What managed tools can I attach to an agent?
Attach any combination of four managed tools, each a separate AgentCore resource referenced by name: useMemory for persistent memory (with optional eventRetentionDays retention), useGateway for a governed tool gateway, useBrowser for a sandboxed browser, and useCodeInterpreter for a code execution environment. You can attach all four at once. Skip useBrowser and useCodeInterpreter unless needed — each adds a managed sandbox and increases the resource footprint.
How do I access other AWS resources from my agent?
Use connectTo to grant your agent access to Stacktape resources like DynamoDB tables, S3 buckets, SQS queues, and databases. For supported target resource types, connectTo grants IAM permissions and provides STP_[RESOURCE_NAME]_[PARAM] connection values as documented in Connecting resources. For AWS services outside Stacktape's resource model, use iamRoleStatements to add custom IAM permissions.
When should I use AgentCore Runtime vs a Lambda function for AI?
Use AgentCore Runtime when your agent needs lifecycle control (maxLifetimeSeconds, idleTimeoutSeconds), multi-turn conversations, or tool attachments (useMemory, useBrowser, useCodeInterpreter, useGateway). Use a Lambda function when you're building a stateless AI endpoint — a single model call that returns a response. Lambda is simpler and cheaper for request/response workloads; AgentCore Runtime is purpose-built for agents with longer-running sessions and tool integrations. For an always-on container with full control over scaling and networking, use a web service instead.
How do I secure my agent endpoints?
Use the authorizer property to configure JWT-based authentication. Provide your OIDC provider's discoveryUrl (the only required field), and optionally restrict access by audience (allowedAudience), client ID (allowedClients), or scope (allowedScopes). JWT auth requires an OIDC provider such as Amazon Cognito or Auth0. Configure an authorizer for any endpoint exposed to the public internet.
How is AWS Bedrock AgentCore priced?
Bedrock AgentCore pricing is session-based — you pay for active runtime sessions rather than reserved compute capacity. Because cost scales with session count and duration, a shorter idleTimeoutSeconds reclaims idle sessions sooner and lowers cost. Pricing varies by region; check the AWS Bedrock pricing page for current rates.
How does AgentCore Runtime handle concurrency?
AgentCore Runtime concurrency and scaling are managed by AWS Bedrock AgentCore, not configured directly in Stacktape. You control per-session behavior through the lifecycle property (idleTimeoutSeconds, maxLifetimeSeconds) but do not set instance counts or autoscaling policies on the runtime resource itself. For detailed concurrency limits and quotas, check the AWS Bedrock AgentCore documentation.
API Reference
AgentCoreRuntimePropsReferenceable parameters
AgentCore Runtime exposes the following parameters, accessible via the $ResourceParam directive:
| Parameter | Description |
|---|---|
id | The runtime resource ID |
arn | The runtime ARN |
endpointName | The deployed endpoint name |
endpointArn | The endpoint ARN |