AWS Bedrock AgentCore Runtime invocation timeout: 504 errors and cold-start init limits

This runbook covers AgentCore Runtime invocation failures. For the wider picture of governing agents on AWS, see AWS Loom and governing AI agents. For ongoing agent operations, book a consulting session.

Symptoms

The failure shows up in one of three shapes. Identify yours first, because the fix differs.

# 1. Cold-start / initialisation timeout
An error occurred (RuntimeClientError) when calling the InvokeAgentRuntime
operation: Runtime initialization time exceeded. Please make sure that
initialization completes in 60s.

# 2. Gateway timeout during invocation
HTTP 504 Gateway Timeout

# 3. Silent hang / retry loop
# The entrypoint is re-invoked roughly every 60 seconds and the caller
# never receives a result. CloudWatch shows repeated invocation starts.

Observable impact:

• First call after a deploy or idle period fails, later calls sometimes succeed (classic cold start)
• Long-running agent turns get cut off partway through
• CloudWatch logs for the runtime show repeated entrypoint starts with no completion

Cause

AgentCore Runtime places three hard constraints on an agent container, and each maps to one of the symptoms above.

1. Initialisation must complete within 60 seconds. Anything your container does before it is ready to serve (loading a model client, warming a cache, importing heavy libraries) counts against this window. Exceed it and the invocation fails with RuntimeClientError.
2. The container contract is strict. The image must expose port 8080 and serve the /invocations path, and it must be built for ARM64. A container that starts but does not meet this contract produces a 504 because the platform cannot route the request to it.
3. Sessions terminate after 15 minutes of inactivity (900 seconds). A long tool call or a slow model response that pushes a single turn past the limit gets interrupted.

Common triggers:

• Heavy work at import time - model clients, embeddings, or large dependencies loaded at module load rather than lazily
• Wrong architecture - an x86_64 image deployed to an ARM64-only runtime
• Missing container contract - the app listens on a port other than 8080, or does not implement /invocations
• Long synchronous turns - a single agent turn that blocks past the session idle limit

Fix

Step 1: Confirm which failure mode you have

Read the runtime’s CloudWatch logs. The error text tells you the mode directly.

# Tail the runtime log group (replace with your runtime id)
aws logs tail /aws/bedrock-agentcore/runtimes/your-agent-runtime-id \
  --since 30m --follow --region us-west-2

If you see “Runtime initialization time exceeded”, go to Step 2. If you see a 504 with no init error, go to Step 3. If the entrypoint restarts on a ~60s cadence with no completion, treat it as a container-contract problem (Step 3) plus a long-turn problem (Step 4).

Step 2: Move heavy work out of the init path

Initialisation must finish in 60 seconds. Defer anything expensive until the first invocation instead of doing it at import time.

# Anti-pattern: heavy work at module load counts against the 60s init budget
# model_client = load_large_client()   # runs on import, can blow the limit

# Better: lazy initialisation on first use
_model_client = None

def get_model_client():
    global _model_client
    if _model_client is None:
        _model_client = load_large_client()
    return _model_client

If initialisation is genuinely heavy, reduce image layers, pre-bake artefacts into the image rather than downloading them at startup, and remove unused dependencies.

Step 3: Verify the container contract

The image must expose port 8080, serve /invocations, and be built for ARM64.

# Confirm the image architecture is arm64
docker inspect your-image:tag --format '{{.Architecture}}'
# Expected: arm64

# Build explicitly for ARM64 if it is not
docker buildx build --platform linux/arm64 -t your-image:tag .

Make sure the app inside the container listens on 8080 and implements the /invocations path (and /ping for health, per the runtime contract). A container that reports “Ready” but never receives a handler call almost always fails one of these.

Step 4: Keep a single turn inside the session limit

Sessions end after 15 minutes of inactivity. For long work, stream progress so the session stays active, or break the work into steps rather than one blocking call.

• Stream partial output back to the caller so the session is not idle
• Offload genuinely long jobs to an async worker and have the agent poll for the result
• Do not design a single agent turn that blocks for more than a few minutes

Step 5: Add a client-side retry for cold starts

A cold start after idle is expected. Retry the first invocation with backoff rather than surfacing the error to the user.

import time, random
from botocore.exceptions import ClientError

def invoke_with_retry(client, runtime_id, payload, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.invoke_agent_runtime(
                agentRuntimeId=runtime_id, payload=payload
            )
        except ClientError as e:
            code = e.response["Error"]["Code"]
            if code == "RuntimeClientError" and attempt < max_retries - 1:
                time.sleep((2 ** attempt) + random.uniform(0, 1))
            else:
                raise

Validation

Confirm a cold invocation now succeeds within the init window.

# Invoke and time the first call after an idle period
time aws bedrock-agentcore invoke-agent-runtime \
  --agent-runtime-id your-agent-runtime-id \
  --payload '{"prompt":"health check"}' \
  --region us-west-2 /dev/stdout

Expected: a successful response with no RuntimeClientError and no 504. Then confirm the logs show a single clean invocation rather than a restart loop:

aws logs tail /aws/bedrock-agentcore/runtimes/your-agent-runtime-id \
  --since 5m --region us-west-2

Expected: one entrypoint start followed by a completion, not repeated starts.

Related

• AWS Loom: governing AI agents on AWS - where AgentCore Runtime fits in the wider platform
• Agent sprawl: governing AI agents before they multiply - why a shared runtime and governance layer matters
• AWS Bedrock AgentCore Runtime troubleshooting documentation