@aws/agentcore 1.0.0-preview.24 → 1.0.0-preview.25

package/dist/assets/README.md

@@ -37,6 +37,11 @@ Run your agent locally:
 agentcore dev
 ```
 
+### Validate Invocation Input
+
+Validate runtime invocation payloads before forwarding them to an agent framework. Keep user prompts typed as strings
+and pass only prompt text to the agent.
+
 ### Deployment
 
 Deploy to AWS:

package/dist/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap

@@ -742,6 +742,12 @@ exports[`Assets Directory Snapshots > File listing > should match the expected f
   "container/typescript/dockerignore.template",
   "datasets/predefined-v1.jsonl",
   "datasets/simulated-v1.jsonl",
+  "evaluators/autoevals-lambda/execution-role-policy.json",
+  "evaluators/autoevals-lambda/lambda_function.py",
+  "evaluators/autoevals-lambda/pyproject.toml",
+  "evaluators/deepeval-lambda/execution-role-policy.json",
+  "evaluators/deepeval-lambda/lambda_function.py",
+  "evaluators/deepeval-lambda/pyproject.toml",
   "evaluators/python-lambda/execution-role-policy.json",
   "evaluators/python-lambda/lambda_function.py",
   "evaluators/python-lambda/pyproject.toml",
@@ -3329,6 +3335,11 @@ file defines a Starlette ASGI app with the AutoGen framework running within.
 
 \`model/load.py\` instantiates your chosen model provider.
 
+## Input Validation
+
+Validate invocation input before forwarding it to the agent framework. Keep plain prompts typed as strings and pass
+only prompt text to the agent.
+
 ## Environment Variables
 
 | Variable | Required | Description |
@@ -3532,6 +3543,8 @@ async def invoke(payload, context):
 
     # Process the user prompt
     prompt = payload.get("prompt", "What can you help me with?")
+    if not isinstance(prompt, str):
+        raise ValueError("prompt must be a string")
     session_id = getattr(context, "session_id", "default-session")
 
     # Reuse the per-session agent (preserves conversation history)
@@ -3785,6 +3798,11 @@ file defines a Starlette ASGI app with the Google ADK framework running within.
 
 \`model/load.py\` instantiates your chosen model provider (Gemini).
 
+## Input Validation
+
+Validate invocation input before forwarding it to the agent framework. Keep plain prompts typed as strings and pass
+only prompt text to the agent.
+
 ## Environment Variables
 
 | Variable | Required | Description |
@@ -4052,6 +4070,8 @@ async def invoke(payload, context):
 
     # Process the user prompt
     prompt = payload.get("prompt", "What can you help me with?")
+    if not isinstance(prompt, str):
+        raise ValueError("prompt must be a string")
     session_id = getattr(context, "session_id", "default_session")
     user_id = payload.get("user_id", "default_user")
 
@@ -4245,6 +4265,11 @@ file defines a Starlette ASGI app with the LangChain/LangGraph framework running
 
 \`model/load.py\` instantiates your chosen model provider.
 
+## Input Validation
+
+Validate invocation input before forwarding it to the agent framework. Keep plain prompts typed as strings and pass
+only prompt text to the agent.
+
 ## Environment Variables
 
 | Variable | Required | Description |
@@ -4504,6 +4529,8 @@ async def invoke(payload, context):
 
     # Process the user prompt
     prompt = payload.get("prompt", "What can you help me with?")
+    if not isinstance(prompt, str):
+        raise ValueError("prompt must be a string")
     session_id = getattr(context, "session_id", "default-session")
     touch_thread(session_id)
     log.info(f"Agent input: {prompt}")
@@ -4523,6 +4550,8 @@ async def invoke(payload, context):
 
     # Process the user prompt
     prompt = payload.get("prompt", "What can you help me with?")
+    if not isinstance(prompt, str):
+        raise ValueError("prompt must be a string")
     session_id = getattr(context, "session_id", "default-session")
     touch_thread(session_id)
     log.info(f"Agent input: {prompt}")
@@ -4823,6 +4852,11 @@ file defines a Starlette ASGI app with the OpenAI Agents SDK framework running w
 
 \`model/load.py\` instantiates your chosen model provider (OpenAI).
 
+## Input Validation
+
+Validate invocation input before forwarding it to the agent framework. Keep plain prompts typed as strings and pass
+only prompt text to the agent.
+
 ## Environment Variables
 
 | Variable | Required | Description |
@@ -5083,6 +5117,8 @@ async def invoke(payload, context):
 
     # Process the user prompt
     prompt = payload.get("prompt", "What can you help me with?")
+    if not isinstance(prompt, str):
+        raise ValueError("prompt must be a string")
     session_id = getattr(context, "session_id", "default-session")
     session = get_session(session_id)
 
@@ -5268,6 +5304,12 @@ file defines a Starlette ASGI app with the chosen Agent framework SDK running wi
 
 \`model/load.py\` instantiates your chosen model provider.
 
+## Input Validation
+
+Validate invocation input before forwarding it to Strands. Keep plain prompts typed as strings. If the app accepts a
+caller-supplied message history, retain \`strip_trailing_tool_use()\`, which normalizes the history tail before
+invoking the agent.
+
 ## Environment Variables
 
 | Variable | Required | Description |
@@ -5824,17 +5866,53 @@ get_or_create_agent = agent_factory()
 {{/if}}
 
 
+def strip_trailing_tool_use(messages: Any) -> list[dict]:
+    """Strip toolUse blocks from the tail until the last message has none."""
+    if not isinstance(messages, list):
+        raise ValueError("messages must be a list")
+
+    messages = list(messages)
+    while messages:
+        last = messages[-1]
+        if not isinstance(last, dict):
+            raise ValueError("each message must be an object")
+        original_content = last.get("content", [])
+        if not isinstance(original_content, list) or not all(isinstance(block, dict) for block in original_content):
+            raise ValueError("each message content value must be a list of content blocks")
+
+        content = [block for block in original_content if "toolUse" not in block]
+        if len(content) == len(original_content):
+            break
+        if content:
+            messages[-1] = {**last, "content": content}
+            break
+        messages.pop()
+
+    return messages
+
+
 def _extract_prompt(payload: dict):
-    """Accept harness-style messages[], tool_results[], or plain prompt string payloads."""
+    """Accept validated harness messages, tool results, or a plain prompt string."""
+    if not isinstance(payload, dict):
+        raise ValueError("payload must be a JSON object")
     if "messages" in payload:
-        return payload["messages"]
+        return strip_trailing_tool_use(payload["messages"])
     if "tool_results" in payload:
+        tool_results = payload["tool_results"]
+        if not isinstance(tool_results, list) or not all(
+            isinstance(tool_result, dict) and isinstance(tool_result.get("toolUseId"), str)
+            for tool_result in tool_results
+        ):
+            raise ValueError("tool_results must contain objects with a toolUseId string")
         return [{"role": "user", "content": [{"toolResult": {
             "toolUseId": tr["toolUseId"],
             "status": tr.get("status", "success"),
             "content": tr.get("content", []),
-        }} for tr in payload["tool_results"]]}]
-    return payload.get("prompt", "")
+        }} for tr in tool_results]}]
+    prompt = payload.get("prompt", "")
+    if not isinstance(prompt, str):
+        raise ValueError("prompt must be a string")
+    return prompt
 
 
 def _has_inline_function_call(messages) -> bool:
@@ -7302,6 +7380,11 @@ Run your agent locally:
 agentcore dev
 \`\`\`
 
+### Validate Invocation Input
+
+Validate runtime invocation payloads before forwarding them to an agent framework. Keep user prompts typed as strings
+and pass only prompt text to the agent.
+
 ### Deployment
 
 Deploy to AWS:
@@ -7396,6 +7479,8 @@ Tags defined in \`agentcore.json\` flow through to deployed CloudFormation resou
    \`agentcore validate\` to check.
 4. **Resource Removal:** Use \`agentcore remove\` to remove resources. Run \`agentcore deploy\` after removal to tear down
    deployed infrastructure.
+5. **Invocation Input:** Validate runtime payloads and require text prompts to be strings. If a Strands app accepts a
+   caller-supplied message history, normalize the history tail with \`strip_trailing_tool_use()\` before invocation.
 
 ## Directory Structure
 
@@ -7609,6 +7694,11 @@ defines an HTTP server that streams tokens from your chosen Agent framework SDK.
 
 \`model/load.ts\` instantiates your chosen model provider.
 
+## Input Validation
+
+The generated Zod request schema keeps plain prompts typed as strings before forwarding them to Strands. Retain this
+validation when extending the request shape, and pass only prompt text to the agent.
+
 ## Environment Variables
 
 | Variable | Required | Description |
@@ -7697,6 +7787,10 @@ const SYSTEM_PROMPT = \`
 You are a helpful assistant. Use tools when appropriate.
 \`;
 
+const requestSchema = z.object({
+  prompt: z.string().default(''),
+});
+
 {{#if hasMemory}}
 const agentCache = new Map<string, Agent>();
 
@@ -7750,7 +7844,8 @@ async function getOrCreateAgent(sessionId: string): Promise<Agent> {
 
 const app = new BedrockAgentCoreApp({
   invocationHandler: {
-    async *process(payload: any, context: any) {
+    requestSchema,
+    async *process(payload, context) {
       {{#if hasMemory}}
       const sessionId = context?.sessionId ?? 'default-session';
       const actorId = getActorId(payload, context);
@@ -7762,7 +7857,7 @@ const app = new BedrockAgentCoreApp({
 
       {{#if hasMemory}}
       try {
-        for await (const event of agent.stream(payload.prompt ?? '')) {
+        for await (const event of agent.stream(payload.prompt)) {
           if (
             event.type === 'modelStreamUpdateEvent' &&
             event.event?.type === 'modelContentBlockDeltaEvent' &&
@@ -7786,7 +7881,7 @@ const app = new BedrockAgentCoreApp({
       // e.g. Anthropic). Restoring on error keeps the session reusable.
       const snapshot = agent.takeSnapshot({ include: ['messages'] });
       try {
-        for await (const event of agent.stream(payload.prompt ?? '')) {
+        for await (const event of agent.stream(payload.prompt)) {
           if (
             event.type === 'modelStreamUpdateEvent' &&
             event.event?.type === 'modelContentBlockDeltaEvent' &&
@@ -8066,6 +8161,11 @@ defines an HTTP app that streams tokens using the Vercel AI SDK's \`streamText\`
 
 \`model/load.ts\` instantiates your chosen model provider.
 
+## Input Validation
+
+The generated Zod request schema keeps plain prompts typed as strings before forwarding them to the agent framework.
+Retain this validation when extending the request shape, and pass only prompt text to the agent.
+
 ## Environment Variables
 
 | Variable | Required | Description |
@@ -8120,10 +8220,15 @@ Thumbs.db
 exports[`Assets Directory Snapshots > TypeScript assets > typescript/typescript/http/vercelai/base/main.ts should match snapshot 1`] = `
 "import { BedrockAgentCoreApp } from 'bedrock-agentcore/runtime';
 import { streamText, type ModelMessage } from 'ai';
+import { z } from 'zod';
 import { loadModel } from './model/load.js';
 
 const SYSTEM_PROMPT = \`You are a helpful assistant.\`;
 
+const requestSchema = z.object({
+  prompt: z.string().default(''),
+});
+
 const HISTORY_LIMIT = 128;
 
 // Keeps one message history per sessionId so each session remembers its own
@@ -8152,10 +8257,11 @@ function getHistory(sessionId: string): ModelMessage[] {
 
 const app = new BedrockAgentCoreApp({
   invocationHandler: {
-    async *process(payload: any, context: any) {
+    requestSchema,
+    async *process(payload, context) {
       const sessionId = context?.sessionId ?? 'default-session';
       const history = getHistory(sessionId);
-      const userMessage: ModelMessage = { role: 'user', content: payload.prompt ?? '' };
+      const userMessage: ModelMessage = { role: 'user', content: payload.prompt };
 
       const model = await loadModel();
       const result = streamText({

package/dist/assets/__tests__/input-validation.test.ts

@@ -0,0 +1,44 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const ASSETS_DIR = resolve(__dirname, '..');
+
+const PYTHON_HTTP_ENTRYPOINTS = [
+  'python/http/autogen/base/main.py',
+  'python/http/googleadk/base/main.py',
+  'python/http/langchain_langgraph/base/main.py',
+  'python/http/openaiagents/base/main.py',
+  'python/http/strands/base/main.py',
+];
+
+const TYPESCRIPT_HTTP_ENTRYPOINTS = [
+  'typescript/http/strands/base/main.ts',
+  'typescript/http/vercelai/base/main.ts',
+];
+
+describe('HTTP agent template input validation', () => {
+  it.each(PYTHON_HTTP_ENTRYPOINTS)('%s rejects non-string prompts', templatePath => {
+    const template = readFileSync(resolve(ASSETS_DIR, templatePath), 'utf8');
+
+    expect(template).toContain('if not isinstance(prompt, str):');
+    expect(template).toContain('raise ValueError("prompt must be a string")');
+  });
+
+  it.each(TYPESCRIPT_HTTP_ENTRYPOINTS)('%s validates prompts with Zod', templatePath => {
+    const template = readFileSync(resolve(ASSETS_DIR, templatePath), 'utf8');
+
+    expect(template).toContain("prompt: z.string().default('')");
+    expect(template).toContain('requestSchema,');
+  });
+
+  it('strips toolUse blocks from the Python Strands message-history tail', () => {
+    const template = readFileSync(resolve(ASSETS_DIR, 'python/http/strands/base/main.py'), 'utf8');
+
+    expect(template).toContain('def strip_trailing_tool_use(messages: Any) -> list[dict]:');
+    expect(template).toContain('while messages:');
+    expect(template).toContain('content = [block for block in original_content if "toolUse" not in block]');
+    expect(template).toContain('messages.pop()');
+    expect(template).toContain('return strip_trailing_tool_use(payload["messages"])');
+  });
+});

package/dist/assets/agents/AGENTS.md

@@ -23,6 +23,8 @@ Tags defined in `agentcore.json` flow through to deployed CloudFormation resourc
    `agentcore validate` to check.
 4. **Resource Removal:** Use `agentcore remove` to remove resources. Run `agentcore deploy` after removal to tear down
    deployed infrastructure.
+5. **Invocation Input:** Validate runtime payloads and require text prompts to be strings. If a Strands app accepts a
+   caller-supplied message history, normalize the history tail with `strip_trailing_tool_use()` before invocation.
 
 ## Directory Structure
 

package/dist/assets/evaluators/autoevals-lambda/execution-role-policy.json

@@ -0,0 +1,15 @@
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": ["logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents"],
+      "Resource": "arn:*:logs:*:*:log-group:/aws/lambda/*"
+    },
+    {
+      "Effect": "Allow",
+      "Action": ["bedrock:InvokeModel"],
+      "Resource": "*"
+    }
+  ]
+}

package/dist/assets/evaluators/autoevals-lambda/lambda_function.py

@@ -0,0 +1,37 @@
+{{#if ModelProviderBedrock}}
+import os
+
+# litellm's Bedrock provider reads AWS_REGION_NAME; Lambda only sets AWS_REGION/AWS_DEFAULT_REGION.
+os.environ.setdefault("AWS_REGION_NAME", os.environ.get("AWS_REGION", "us-west-2"))
+
+from autoevals import {{ EvaluatorClass }}, init
+from autoevals.litellm import LiteLLMClient
+
+from bedrock_agentcore.evaluation.custom_code_based_evaluators import (
+    EvaluatorInput,
+    EvaluatorOutput,
+    custom_code_based_evaluator,
+)
+from bedrock_agentcore.evaluation.custom_code_based_evaluators.third_party.autoevals import AutoEvalsAdapter
+
+client = LiteLLMClient()
+init(client=client, default_model="{{ Model }}")
+
+adapter = AutoEvalsAdapter(metric={{ EvaluatorClass }}(client=client, model="{{ Model }}"){{#if EvaluatorParams}}, {{{ EvaluatorParams }}}{{/if}})
+{{else}}
+from autoevals import {{ EvaluatorClass }}
+
+from bedrock_agentcore.evaluation.custom_code_based_evaluators import (
+    EvaluatorInput,
+    EvaluatorOutput,
+    custom_code_based_evaluator,
+)
+from bedrock_agentcore.evaluation.custom_code_based_evaluators.third_party.autoevals import AutoEvalsAdapter
+
+adapter = AutoEvalsAdapter(metric={{ EvaluatorClass }}({{#if Model}}model="{{ Model }}"{{/if}}){{#if EvaluatorParams}}, {{{ EvaluatorParams }}}{{/if}})
+{{/if}}
+
+
+@custom_code_based_evaluator()
+def handler(evaluator_input: EvaluatorInput, context) -> EvaluatorOutput:
+    return adapter(evaluator_input, context)

package/dist/assets/evaluators/autoevals-lambda/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{{ Name }}"
+version = "0.1.0"
+description = "AgentCore Code-Based Evaluator (Autoevals)"
+requires-python = ">=3.10"
+dependencies = [
+    "bedrock-agentcore[autoevals]",
+    "autoevals>=0.0.80,<1.0.0",
+{{#if ModelProviderBedrock}}
+    # autoevals grades via LiteLLMClient -> Bedrock (Converse); litellm replaces the openai judge
+    "litellm>=1.60,<1.85",
+{{else}}
+    "openai>=1.0.0",
+{{/if}}
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]

package/dist/assets/evaluators/deepeval-lambda/execution-role-policy.json

@@ -0,0 +1,15 @@
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": ["logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents"],
+      "Resource": "arn:*:logs:*:*:log-group:/aws/lambda/*"
+    },
+    {
+      "Effect": "Allow",
+      "Action": ["bedrock:InvokeModel"],
+      "Resource": "*"
+    }
+  ]
+}

package/dist/assets/evaluators/deepeval-lambda/lambda_function.py

@@ -0,0 +1,29 @@
+import os
+
+os.environ.setdefault("DEEPEVAL_RESULTS_FOLDER", "/tmp/.deepeval")
+os.environ.setdefault("DEEPEVAL_TELEMETRY_OPT_OUT", "YES")
+os.chdir("/tmp")
+
+{{#if ModelProviderBedrock}}
+from deepeval.models import AmazonBedrockModel
+{{/if}}
+from deepeval.metrics import {{ EvaluatorClass }}
+
+from bedrock_agentcore.evaluation.custom_code_based_evaluators import (
+    EvaluatorInput,
+    EvaluatorOutput,
+    custom_code_based_evaluator,
+)
+from bedrock_agentcore.evaluation.custom_code_based_evaluators.third_party.deepeval import DeepEvalAdapter
+
+{{#if ModelProviderBedrock}}
+model = AmazonBedrockModel(model="{{ Model }}", region=os.environ.get("AWS_REGION", "us-west-2"))
+adapter = DeepEvalAdapter(metric={{ EvaluatorClass }}(model=model{{#if EvaluatorParams}}, {{{ EvaluatorParams }}}{{/if}}))
+{{else}}
+adapter = DeepEvalAdapter(metric={{ EvaluatorClass }}({{{ EvaluatorParams }}}))
+{{/if}}
+
+
+@custom_code_based_evaluator()
+def handler(evaluator_input: EvaluatorInput, context) -> EvaluatorOutput:
+    return adapter(evaluator_input, context)

package/dist/assets/evaluators/deepeval-lambda/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{{ Name }}"
+version = "0.1.0"
+description = "AgentCore Code-Based Evaluator (DeepEval)"
+requires-python = ">=3.10"
+dependencies = [
+    "bedrock-agentcore[deepeval]",
+    "deepeval>=2.0.0,<3.0.0",
+{{#if ModelProviderBedrock}}
+    "aiobotocore>=2.13.0",
+{{/if}}
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]

package/dist/assets/python/http/autogen/base/README.md

@@ -13,6 +13,11 @@ file defines a Starlette ASGI app with the AutoGen framework running within.
 
 `model/load.py` instantiates your chosen model provider.
 
+## Input Validation
+
+Validate invocation input before forwarding it to the agent framework. Keep plain prompts typed as strings and pass
+only prompt text to the agent.
+
 ## Environment Variables
 
 | Variable | Required | Description |

package/dist/assets/python/http/autogen/base/main.py

@@ -127,6 +127,8 @@ async def invoke(payload, context):
 
     # Process the user prompt
     prompt = payload.get("prompt", "What can you help me with?")
+    if not isinstance(prompt, str):
+        raise ValueError("prompt must be a string")
     session_id = getattr(context, "session_id", "default-session")
 
     # Reuse the per-session agent (preserves conversation history)

package/dist/assets/python/http/googleadk/base/README.md

@@ -13,6 +13,11 @@ file defines a Starlette ASGI app with the Google ADK framework running within.
 
 `model/load.py` instantiates your chosen model provider (Gemini).
 
+## Input Validation
+
+Validate invocation input before forwarding it to the agent framework. Keep plain prompts typed as strings and pass
+only prompt text to the agent.
+
 ## Environment Variables
 
 | Variable | Required | Description |

package/dist/assets/python/http/googleadk/base/main.py

@@ -191,6 +191,8 @@ async def invoke(payload, context):
 
     # Process the user prompt
     prompt = payload.get("prompt", "What can you help me with?")
+    if not isinstance(prompt, str):
+        raise ValueError("prompt must be a string")
     session_id = getattr(context, "session_id", "default_session")
     user_id = payload.get("user_id", "default_user")
 

package/dist/assets/python/http/langchain_langgraph/base/README.md

@@ -13,6 +13,11 @@ file defines a Starlette ASGI app with the LangChain/LangGraph framework running
 
 `model/load.py` instantiates your chosen model provider.
 
+## Input Validation
+
+Validate invocation input before forwarding it to the agent framework. Keep plain prompts typed as strings and pass
+only prompt text to the agent.
+
 ## Environment Variables
 
 | Variable | Required | Description |

package/dist/assets/python/http/langchain_langgraph/base/main.py

@@ -183,6 +183,8 @@ async def invoke(payload, context):
 
     # Process the user prompt
     prompt = payload.get("prompt", "What can you help me with?")
+    if not isinstance(prompt, str):
+        raise ValueError("prompt must be a string")
     session_id = getattr(context, "session_id", "default-session")
     touch_thread(session_id)
     log.info(f"Agent input: {prompt}")
@@ -202,6 +204,8 @@ async def invoke(payload, context):
 
     # Process the user prompt
     prompt = payload.get("prompt", "What can you help me with?")
+    if not isinstance(prompt, str):
+        raise ValueError("prompt must be a string")
     session_id = getattr(context, "session_id", "default-session")
     touch_thread(session_id)
     log.info(f"Agent input: {prompt}")

package/dist/assets/python/http/openaiagents/base/README.md

@@ -13,6 +13,11 @@ file defines a Starlette ASGI app with the OpenAI Agents SDK framework running w
 
 `model/load.py` instantiates your chosen model provider (OpenAI).
 
+## Input Validation
+
+Validate invocation input before forwarding it to the agent framework. Keep plain prompts typed as strings and pass
+only prompt text to the agent.
+
 ## Environment Variables
 
 | Variable | Required | Description |

package/dist/assets/python/http/openaiagents/base/main.py

@@ -184,6 +184,8 @@ async def invoke(payload, context):
 
     # Process the user prompt
     prompt = payload.get("prompt", "What can you help me with?")
+    if not isinstance(prompt, str):
+        raise ValueError("prompt must be a string")
     session_id = getattr(context, "session_id", "default-session")
     session = get_session(session_id)
 

package/dist/assets/python/http/strands/base/README.md

@@ -13,6 +13,12 @@ file defines a Starlette ASGI app with the chosen Agent framework SDK running wi
 
 `model/load.py` instantiates your chosen model provider.
 
+## Input Validation
+
+Validate invocation input before forwarding it to Strands. Keep plain prompts typed as strings. If the app accepts a
+caller-supplied message history, retain `strip_trailing_tool_use()`, which normalizes the history tail before
+invoking the agent.
+
 ## Environment Variables
 
 | Variable | Required | Description |

package/dist/assets/python/http/strands/base/main.py

@@ -481,17 +481,53 @@ get_or_create_agent = agent_factory()
 {{/if}}
 
 
+def strip_trailing_tool_use(messages: Any) -> list[dict]:
+    """Strip toolUse blocks from the tail until the last message has none."""
+    if not isinstance(messages, list):
+        raise ValueError("messages must be a list")
+
+    messages = list(messages)
+    while messages:
+        last = messages[-1]
+        if not isinstance(last, dict):
+            raise ValueError("each message must be an object")
+        original_content = last.get("content", [])
+        if not isinstance(original_content, list) or not all(isinstance(block, dict) for block in original_content):
+            raise ValueError("each message content value must be a list of content blocks")
+
+        content = [block for block in original_content if "toolUse" not in block]
+        if len(content) == len(original_content):
+            break
+        if content:
+            messages[-1] = {**last, "content": content}
+            break
+        messages.pop()
+
+    return messages
+
+
 def _extract_prompt(payload: dict):
-    """Accept harness-style messages[], tool_results[], or plain prompt string payloads."""
+    """Accept validated harness messages, tool results, or a plain prompt string."""
+    if not isinstance(payload, dict):
+        raise ValueError("payload must be a JSON object")
     if "messages" in payload:
-        return payload["messages"]
+        return strip_trailing_tool_use(payload["messages"])
     if "tool_results" in payload:
+        tool_results = payload["tool_results"]
+        if not isinstance(tool_results, list) or not all(
+            isinstance(tool_result, dict) and isinstance(tool_result.get("toolUseId"), str)
+            for tool_result in tool_results
+        ):
+            raise ValueError("tool_results must contain objects with a toolUseId string")
         return [{"role": "user", "content": [{"toolResult": {
             "toolUseId": tr["toolUseId"],
             "status": tr.get("status", "success"),
             "content": tr.get("content", []),
-        }} for tr in payload["tool_results"]]}]
-    return payload.get("prompt", "")
+        }} for tr in tool_results]}]
+    prompt = payload.get("prompt", "")
+    if not isinstance(prompt, str):
+        raise ValueError("prompt must be a string")
+    return prompt
 
 
 def _has_inline_function_call(messages) -> bool: