AgentCore Runtime

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:

export default defineConfig(() => {
  const myAgent = new AgentCoreRuntime({
    packaging: new DockerfilePackaging({
      buildContextPath: './agent'
    }),
    protocol: 'HTTP',
    endpoints: ['chat']
  });

  return {
    resources: { myAgent }
  };
});

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.

export default defineConfig(() => {
  const agentMemory = new AgentCoreMemory({
    eventRetentionDays: 30
  });

  const supportAgent = new AgentCoreRuntime({
    packaging: new DockerfilePackaging({
      buildContextPath: './agent'
    }),
    protocol: 'HTTP',
    useMemory: 'agentMemory',
    endpoints: ['chat'],
    lifecycle: {
      maxLifetimeSeconds: 7200,
      idleTimeoutSeconds: 300
    }
  });

  return {
    resources: { agentMemory, supportAgent }
  };
});

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:

export default defineConfig(() => {
  const agentMemory = new AgentCoreMemory({
    eventRetentionDays: 60
  });

  const toolGateway = new AgentCoreGateway({
    description: 'Gateway for support operations',
    authorizer: { type: 'none' },
    supportedVersions: ['2025-03-26']
  });

  const browser = new AgentCoreBrowser({
    description: 'Sandboxed browser for web research'
  });

  const codeRunner = new AgentCoreCodeInterpreter({
    description: 'Sandboxed code execution'
  });

  const conversations = new DynamoDbTable({
    primaryKey: {
      partitionKey: { name: 'sessionId', type: 'string' }
    }
  });

  const myAgent = new AgentCoreRuntime({
    packaging: new DockerfilePackaging({
      buildContextPath: './'
    }),
    protocol: 'HTTP',
    useMemory: 'agentMemory',
    useGateway: 'toolGateway',
    useBrowser: 'browser',
    useCodeInterpreter: 'codeRunner',
    endpoints: [
      {
        name: 'production',
        description: 'Main agent endpoint'
      }
    ],
    lifecycle: {
      maxLifetimeSeconds: 14400,
      idleTimeoutSeconds: 1800
    },
    connectTo: [conversations],
    authorizer: {
      discoveryUrl:
      'https://cognito-idp.us-east-1.amazonaws.com/us-east-1_abc123/.well-known/openid-configuration',
      allowedAudience: ['my-app-client-id']
    },
    environment: { AI_MODEL: 'anthropic.claude-sonnet-4-20250514' }
  });

  return {
    resources: {
      agentMemory,
      toolGateway,
      browser,
      codeRunner,
      conversations,
      myAgent
    }
  };
});

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:

ProtocolDescription
HTTPStandard HTTP request/response. Works with any HTTP client or framework.
MCPModel Context Protocol. Standardized protocol for tool-calling agents that follow the MCP specification.
A2AAgent-to-Agent protocol. For agents that communicate with other agents using a structured agent protocol.
AGUIAgent 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.

export default defineConfig(() => {
  const myAgent = new AgentCoreRuntime({
    packaging: new DockerfilePackaging({
      buildContextPath: './agent'
    }),
    protocol: 'HTTP',
    endpoints: [
      'chat',
      {
        name: 'analyze',
        description: 'Analyze documents and return structured data'
      }
    ]
  });

  return {
    resources: { myAgent }
  };
});

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:

PropertyResource typeWhat it provides
useMemoryAgentCore MemoryMemory store with optional eventRetentionDays retention
useGatewayAgentCore GatewayMCP-style tool gateway with governed tool definitions
useBrowserAgentCore BrowserSandboxed browser for web research
useCodeInterpreterAgentCore Code InterpreterSandboxed 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.

export default defineConfig(() => {
  const toolGateway = new AgentCoreGateway({
    description: 'MCP tool gateway for support tools',
    authorizer: { type: 'none' },
    supportedVersions: ['2025-03-26']
  });

  const browser = new AgentCoreBrowser({
    description: 'Sandboxed browser for web research'
  });

  const codeRunner = new AgentCoreCodeInterpreter({
    description: 'Sandboxed code execution'
  });

  const myAgent = new AgentCoreRuntime({
    packaging: new DockerfilePackaging({
      buildContextPath: './agent'
    }),
    protocol: 'HTTP',
    useGateway: 'toolGateway',
    useBrowser: 'browser',
    useCodeInterpreter: 'codeRunner',
    endpoints: ['chat']
  });

  return {
    resources: { toolGateway, browser, codeRunner, myAgent }
  };
});

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.
export default defineConfig(() => {
  const myAgent = new AgentCoreRuntime({
    packaging: new DockerfilePackaging({
      buildContextPath: './agent'
    }),
    protocol: 'HTTP',
    endpoints: ['chat'],
    lifecycle: {
      maxLifetimeSeconds: 3600,
      idleTimeoutSeconds: 300
    }
  });

  return {
    resources: { myAgent }
  };
});

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.

export default defineConfig(() => {
  const myAgent = new AgentCoreRuntime({
    packaging: new DockerfilePackaging({
      buildContextPath: './agent'
    }),
    protocol: 'HTTP',
    endpoints: ['chat'],
    authorizer: {
      discoveryUrl:
      'https://cognito-idp.us-east-1.amazonaws.com/us-east-1_abc123/.well-known/openid-configuration',
      allowedAudience: ['my-app-client-id'],
      allowedClients: ['trusted-client'],
      allowedScopes: ['agent:invoke']
    }
  });

  return {
    resources: { myAgent }
  };
});
PropertyPurpose
discoveryUrlOIDC discovery endpoint URL (required)
allowedAudienceValid aud claim values
allowedClientsValid client IDs in the token
allowedScopesRequired 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.

export default defineConfig(() => {
  const knowledgeBase = new Bucket({});

  const conversationLog = new DynamoDbTable({
    primaryKey: {
      partitionKey: { name: 'sessionId', type: 'string' }
    }
  });

  const myAgent = new AgentCoreRuntime({
    packaging: new DockerfilePackaging({
      buildContextPath: './agent'
    }),
    protocol: 'HTTP',
    endpoints: ['chat'],
    connectTo: [knowledgeBase, conversationLog]
  });

  return {
    resources: { knowledgeBase, conversationLog, myAgent }
  };
});

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:

export default defineConfig(() => {
  const myAgent = new AgentCoreRuntime({
    packaging: new DockerfilePackaging({
      buildContextPath: './agent'
    }),
    protocol: 'HTTP',
    endpoints: ['chat'],
    iamRoleStatements: [
      {
        Effect: 'Allow',
        Action: ['bedrock:InvokeModel'],
        Resource: ['arn:aws:bedrock:*::foundation-model/anthropic.claude-*']
      }
    ]
  });

  return {
    resources: { myAgent }
  };
});

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:

TypeClassWhen to use
js-bundleJsBundleImagePackagingA JavaScript or TypeScript agent with one entry file.
buildpackBuildpackImagePackagingBuild from source without a Dockerfile. The language and start command are detected. Suits Python agents.
dockerfileDockerfilePackagingFull control over the container environment. Use when you need specific system dependencies or a custom base image.
prebuilt-imagePrebuiltImagePackagingReference 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.

export default defineConfig(() => {
  const myAgent = new AgentCoreRuntime({
    packaging: new DockerfilePackaging({
      buildContextPath: './agent'
    }),
    protocol: 'HTTP',
    endpoints: ['chat'],
    environment: {
      AI_MODEL: 'anthropic.claude-sonnet-4-20250514',
      MAX_TOKENS: '4096',
      API_KEY: "$Secret('my-api-key')"
    }
  });

  return {
    resources: { myAgent }
  };
});

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:

export default defineConfig(() => {
  const myAgent = new AgentCoreRuntime({
    packaging: new DockerfilePackaging({
      buildContextPath: './agent'
    }),
    protocol: 'HTTP',
    endpoints: ['chat'],
    requestHeaders: ['X-Tenant-Id', 'X-Trace-Id']
  });

  return {
    resources: { myAgent }
  };
});

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

AgentCoreRuntimeProps
Click a property in the tree to see its description, default value, and full type.

Referenceable parameters

AgentCore Runtime exposes the following parameters, accessible via the $ResourceParam directive:

ParameterDescription
idThe runtime resource ID
arnThe runtime ARN
endpointNameThe deployed endpoint name
endpointArnThe endpoint ARN