fix(py#strands-agent): extract session ID from header instead of request body (#557)

* fix(py#strands-agent): extract session ID from header instead of request body

Align the Python strands agent with the TypeScript implementation by reading
the session ID from the `x-amzn-bedrock-agentcore-runtime-session-id` HTTP
header (the Bedrock AgentCore standard) instead of requiring it in the POST
request body. A random UUID is generated as fallback when the header is absent.

Also renames the input field from `prompt` to `message` for consistency with
the TypeScript agent's input schema.

* docs: update translations

* fix(py#strands-agent): use Request to extract session ID header

Use FastAPI's Request object instead of Header() dependency to extract
the session ID from the x-amzn-bedrock-agentcore-runtime-session-id
header. This avoids the header appearing in the OpenAPI spec, which
caused @hey-api/openapi-ts to generate invalid TypeScript types for the
long hyphenated header name.

* docs: update translations

---------

Co-authored-by: nx-plugin-for-aws <nx-plugin@amazon.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 3 people

docs/src/content/docs/en/get_started/tutorials/dungeon-game/1.mdx

@@ -454,27 +454,31 @@ This creates an example Strands agent and defines an addition tool.
 
 ```python
 # agent/main.py
+import uuid
+
 import uvicorn
 from bedrock_agentcore.runtime.models import PingStatus
+from fastapi import Request
 from pydantic import BaseModel
 
 from .agent import get_agent
 from .init import JsonStreamingResponse, app
 
+SESSION_ID_HEADER = "x-amzn-bedrock-agentcore-runtime-session-id"
+
 
 class InvokeInput(BaseModel):
-    prompt: str
-    session_id: str
+    message: str
 
 
 class StreamChunk(BaseModel):
     content: str
 
 
-async def handle_invoke(input: InvokeInput):
+async def handle_invoke(input: InvokeInput, session_id: str):
     """Streaming handler for agent invocation"""
-    with get_agent(session_id=input.session_id) as agent:
-        stream = agent.stream_async(input.prompt)
+    with get_agent(session_id=session_id) as agent:
+        stream = agent.stream_async(input.message)
         async for event in stream:
             print(event)
             text = event.get("event", {}).get("contentBlockDelta", {}).get("delta", {}).get("text")
@@ -489,9 +493,10 @@ async def handle_invoke(input: InvokeInput):
     response_class=JsonStreamingResponse,
     responses={200: JsonStreamingResponse.openapi_response(StreamChunk, "Stream of agent response chunks")},
 )
-async def invoke(input: InvokeInput) -> JsonStreamingResponse:
+async def invoke(input: InvokeInput, request: Request) -> JsonStreamingResponse:
     """Entry point for agent invocation"""
-    return JsonStreamingResponse(handle_invoke(input))
+    session_id = request.headers.get(SESSION_ID_HEADER) or str(uuid.uuid4())
+    return JsonStreamingResponse(handle_invoke(input, session_id))
 
 
 @app.get("/ping")

docs/src/content/docs/en/guides/py-strands-agent.mdx

@@ -191,18 +191,19 @@ The agent's invocation endpoint uses [Pydantic](https://docs.pydantic.dev/) mode
 
 #### Defining Input Models
 
-The default `InvokeInput` model accepts a prompt and session ID.
+The default `InvokeInput` model accepts a message.
 
 ```python
 from pydantic import BaseModel
 
 class InvokeInput(BaseModel):
-    prompt: str
-    session_id: str
+    message: str
 ```
 
 You can extend this model to include any additional fields your agent needs.
 
+The session ID is extracted from the `x-amzn-bedrock-agentcore-runtime-session-id` HTTP header, consistent with the [Bedrock AgentCore Runtime session contract](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html). If the header is not provided, a random UUID is generated as a fallback.
+
 :::caution[Code Organization]
 You will likely want to abstract some or all of the session ID from the caller if users are to invoke your agent directly. For example, you may use the authenticated user ID as part of the session ID.
 
@@ -302,7 +303,7 @@ To invoke an Agent running locally via the `<your-agent-name>-serve` target, you
 
 ```bash
 curl -N -X POST http://localhost:8081/invocations \
-  -d '{"prompt": "what is 3 + 5?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
+  -d '{"message": "what is 3 + 5?"}' \
   -H "Content-Type: application/json"
 ```
 
@@ -337,7 +338,7 @@ For Cognito Authentication, pass the Cognito Access Token in the `Authorization`
 ```bash
 curl -N -X POST 'https://bedrock
 -agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
-  -d '{"prompt": "what is 3 + 5?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
+  -d '{"message": "what is 3 + 5?"}' \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer <access-token>"
 ```

docs/src/content/docs/es/get_started/tutorials/dungeon-game/1.mdx

@@ -454,27 +454,31 @@ Esto crea un agente Strands de ejemplo y define una herramienta de suma.
 
 ```python
 # agent/main.py
+import uuid
+
 import uvicorn
 from bedrock_agentcore.runtime.models import PingStatus
+from fastapi import Request
 from pydantic import BaseModel
 
 from .agent import get_agent
 from .init import JsonStreamingResponse, app
 
+SESSION_ID_HEADER = "x-amzn-bedrock-agentcore-runtime-session-id"
+
 
 class InvokeInput(BaseModel):
-    prompt: str
-    session_id: str
+    message: str
 
 
 class StreamChunk(BaseModel):
     content: str
 
 
-async def handle_invoke(input: InvokeInput):
+async def handle_invoke(input: InvokeInput, session_id: str):
     """Manejador de streaming para invocación del agente"""
-    with get_agent(session_id=input.session_id) as agent:
-        stream = agent.stream_async(input.prompt)
+    with get_agent(session_id=session_id) as agent:
+        stream = agent.stream_async(input.message)
         async for event in stream:
             print(event)
             text = event.get("event", {}).get("contentBlockDelta", {}).get("delta", {}).get("text")
@@ -489,9 +493,10 @@ async def handle_invoke(input: InvokeInput):
     response_class=JsonStreamingResponse,
     responses={200: JsonStreamingResponse.openapi_response(StreamChunk, "Stream of agent response chunks")},
 )
-async def invoke(input: InvokeInput) -> JsonStreamingResponse:
+async def invoke(input: InvokeInput, request: Request) -> JsonStreamingResponse:
     """Punto de entrada para invocación del agente"""
-    return JsonStreamingResponse(handle_invoke(input))
+    session_id = request.headers.get(SESSION_ID_HEADER) or str(uuid.uuid4())
+    return JsonStreamingResponse(handle_invoke(input, session_id))
 
 
 @app.get("/ping")

docs/src/content/docs/es/guides/py-strands-agent.mdx

@@ -191,18 +191,19 @@ El endpoint de invocación del agente usa modelos [Pydantic](https://docs.pydant
 
 #### Definiendo Modelos de Entrada
 
-El modelo `InvokeInput` por defecto acepta un prompt y un ID de sesión.
+El modelo `InvokeInput` por defecto acepta un mensaje.
 
 ```python
 from pydantic import BaseModel
 
 class InvokeInput(BaseModel):
-    prompt: str
-    session_id: str
+    message: str
 ```
 
 Puedes extender este modelo para incluir cualquier campo adicional que tu agente necesite.
 
+El ID de sesión se extrae del header HTTP `x-amzn-bedrock-agentcore-runtime-session-id`, de acuerdo con el [contrato de sesión de Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html). Si el header no se proporciona, se genera un UUID aleatorio como alternativa.
+
 :::caution[Organización del código]
 Probablemente querrás abstraer parte o todo el ID de sesión del llamador si los usuarios van a invocar tu agente directamente. Por ejemplo, puedes usar el ID de usuario autenticado como parte del ID de sesión.
 
@@ -300,7 +301,7 @@ Para invocar un Agente ejecutándose localmente mediante el target `<your-agent-
 
 ```bash
 curl -N -X POST http://localhost:8081/invocations \
-  -d '{"prompt": "what is 3 + 5?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
+  -d '{"message": "what is 3 + 5?"}' \
   -H "Content-Type: application/json"
 ```
 
@@ -335,7 +336,7 @@ Para autenticación Cognito, pasa el Access Token de Cognito en el header `Autho
 ```bash
 curl -N -X POST 'https://bedrock
 -agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
-  -d '{"prompt": "what is 3 + 5?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
+  -d '{"message": "what is 3 + 5?"}' \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer <access-token>"
 ```

docs/src/content/docs/fr/get_started/tutorials/dungeon-game/1.mdx

@@ -455,27 +455,31 @@ Cela crée un exemple d'agent Strands et définit un outil d'addition.
 
 ```python
 # agent/main.py
+import uuid
+
 import uvicorn
 from bedrock_agentcore.runtime.models import PingStatus
+from fastapi import Request
 from pydantic import BaseModel
 
 from .agent import get_agent
 from .init import JsonStreamingResponse, app
 
+SESSION_ID_HEADER = "x-amzn-bedrock-agentcore-runtime-session-id"
+
 
 class InvokeInput(BaseModel):
-    prompt: str
-    session_id: str
+    message: str
 
 
 class StreamChunk(BaseModel):
     content: str
 
 
-async def handle_invoke(input: InvokeInput):
+async def handle_invoke(input: InvokeInput, session_id: str):
     """Handler de streaming pour l'invocation de l'agent"""
-    with get_agent(session_id=input.session_id) as agent:
-        stream = agent.stream_async(input.prompt)
+    with get_agent(session_id=session_id) as agent:
+        stream = agent.stream_async(input.message)
         async for event in stream:
             print(event)
             text = event.get("event", {}).get("contentBlockDelta", {}).get("delta", {}).get("text")
@@ -490,9 +494,10 @@ async def handle_invoke(input: InvokeInput):
     response_class=JsonStreamingResponse,
     responses={200: JsonStreamingResponse.openapi_response(StreamChunk, "Stream of agent response chunks")},
 )
-async def invoke(input: InvokeInput) -> JsonStreamingResponse:
+async def invoke(input: InvokeInput, request: Request) -> JsonStreamingResponse:
     """Point d'entrée pour l'invocation de l'agent"""
-    return JsonStreamingResponse(handle_invoke(input))
+    session_id = request.headers.get(SESSION_ID_HEADER) or str(uuid.uuid4())
+    return JsonStreamingResponse(handle_invoke(input, session_id))
 
 
 @app.get("/ping")

docs/src/content/docs/fr/guides/py-strands-agent.mdx

@@ -191,18 +191,19 @@ Le point de terminaison d'invocation de l'agent utilise des modèles [Pydantic](
 
 #### Définition des modèles d'entrée
 
-Le modèle `InvokeInput` par défaut accepte un prompt et un ID de session.
+Le modèle `InvokeInput` par défaut accepte un message.
 
 ```python
 from pydantic import BaseModel
 
 class InvokeInput(BaseModel):
-    prompt: str
-    session_id: str
+    message: str
 ```
 
 Vous pouvez étendre ce modèle pour inclure tous les champs supplémentaires dont votre agent a besoin.
 
+L'ID de session est extrait de l'en-tête HTTP `x-amzn-bedrock-agentcore-runtime-session-id`, conformément au [contrat de session Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html). Si l'en-tête n'est pas fourni, un UUID aléatoire est généré par défaut.
+
 :::caution[Organisation du code]
 Vous voudrez probablement abstraire tout ou partie de l'ID de session de l'appelant si les utilisateurs doivent invoquer votre agent directement. Par exemple, vous pouvez utiliser l'ID utilisateur authentifié comme partie de l'ID de session.
 
@@ -302,7 +303,7 @@ Pour invoquer un agent exécuté localement via la cible `<your-agent-name>-serv
 
 ```bash
 curl -N -X POST http://localhost:8081/invocations \
-  -d '{"prompt": "what is 3 + 5?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
+  -d '{"message": "what is 3 + 5?"}' \
   -H "Content-Type: application/json"
 ```
 
@@ -337,7 +338,7 @@ Pour l'authentification Cognito, passez le jeton d'accès Cognito dans l'en-têt
 ```bash
 curl -N -X POST 'https://bedrock
 -agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
-  -d '{"prompt": "what is 3 + 5?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
+  -d '{"message": "what is 3 + 5?"}' \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer <access-token>"
 ```

docs/src/content/docs/it/get_started/tutorials/dungeon-game/1.mdx

@@ -54,7 +54,7 @@ Questo configurerà un monorepo NX all'interno della directory `dungeon-adventur
 
 Ora possiamo iniziare a creare i diversi sotto-progetti utilizzando `@aws/nx-plugin`.
 
-<Aside type="tip">È una best practice assicurarsi che tutti i file non staged siano committati in Git prima di eseguire qualsiasi generatore. Questo permette di visualizzare le modifiche dopo l'esecuzione tramite `git diff`.</Aside>
+<Aside type="tip" title="Committa spesso">È una best practice assicurarsi che tutti i file non staged siano committati in Git prima di eseguire qualsiasi generatore. Questo permette di visualizzare le modifiche dopo l'esecuzione tramite `git diff`.</Aside>
 
 ## Task 2: Creare una Game API
 
@@ -454,27 +454,31 @@ Questo crea un agente Strands di esempio e definisce uno strumento di addizione.
 
 ```python
 # agent/main.py
+import uuid
+
 import uvicorn
 from bedrock_agentcore.runtime.models import PingStatus
+from fastapi import Request
 from pydantic import BaseModel
 
 from .agent import get_agent
 from .init import JsonStreamingResponse, app
 
+SESSION_ID_HEADER = "x-amzn-bedrock-agentcore-runtime-session-id"
+
 
 class InvokeInput(BaseModel):
-    prompt: str
-    session_id: str
+    message: str
 
 
 class StreamChunk(BaseModel):
     content: str
 
 
-async def handle_invoke(input: InvokeInput):
+async def handle_invoke(input: InvokeInput, session_id: str):
     """Handler di streaming per l'invocazione dell'agente"""
-    with get_agent(session_id=input.session_id) as agent:
-        stream = agent.stream_async(input.prompt)
+    with get_agent(session_id=session_id) as agent:
+        stream = agent.stream_async(input.message)
         async for event in stream:
             print(event)
             text = event.get("event", {}).get("contentBlockDelta", {}).get("delta", {}).get("text")
@@ -489,9 +493,10 @@ async def handle_invoke(input: InvokeInput):
     response_class=JsonStreamingResponse,
     responses={200: JsonStreamingResponse.openapi_response(StreamChunk, "Stream of agent response chunks")},
 )
-async def invoke(input: InvokeInput) -> JsonStreamingResponse:
+async def invoke(input: InvokeInput, request: Request) -> JsonStreamingResponse:
     """Entry point per l'invocazione dell'agente"""
-    return JsonStreamingResponse(handle_invoke(input))
+    session_id = request.headers.get(SESSION_ID_HEADER) or str(uuid.uuid4())
+    return JsonStreamingResponse(handle_invoke(input, session_id))
 
 
 @app.get("/ping")
@@ -1096,7 +1101,7 @@ new ApplicationStage(app, 'dungeon-adventure-infra-sandbox', {
 app.synth();
 ```
 
-<Aside type="tip">Se vedi un errore di import nel tuo IDE, è perché il progetto infrastruttura non ha ancora un riferimento TypeScript configurato nel `tsconfig.json`. Nx è stato [configurato](https://nx.dev/nx-api/js/generators/typescript-sync) per creare questi riferimenti *dinamicamente* ogni volta che viene eseguita una build/compilazione o se esegui manualmente il comando `nx sync`. Per maggiori informazioni consulta la <Link path="guides/typescript-project#importing-your-library-code-in-other-projects">guida TypeScript</Link>.</Aside>
+<Aside type="tip" title="Correggere errori di import">Se vedi un errore di import nel tuo IDE, è perché il progetto infrastruttura non ha ancora un riferimento TypeScript configurato nel `tsconfig.json`. Nx è stato [configurato](https://nx.dev/nx-api/js/generators/typescript-sync) per creare questi riferimenti *dinamicamente* ogni volta che viene eseguita una build/compilazione o se esegui manualmente il comando `nx sync`. Per maggiori informazioni consulta la <Link path="guides/typescript-project#importing-your-library-code-in-other-projects">guida TypeScript</Link>.</Aside>
 
 Questo è l'entry point per l'applicazione CDK.
 

docs/src/content/docs/it/guides/py-strands-agent.mdx

@@ -191,18 +191,19 @@ L'endpoint di invocazione dell'agente utilizza modelli [Pydantic](https://docs.p
 
 #### Definire Modelli di Input
 
-Il modello `InvokeInput` predefinito accetta un prompt e un ID di sessione.
+Il modello `InvokeInput` predefinito accetta un messaggio.
 
 ```python
 from pydantic import BaseModel
 
 class InvokeInput(BaseModel):
-    prompt: str
-    session_id: str
+    message: str
 ```
 
 Puoi estendere questo modello per includere qualsiasi campo aggiuntivo di cui il tuo agente ha bisogno.
 
+L'ID di sessione viene estratto dall'header HTTP `x-amzn-bedrock-agentcore-runtime-session-id`, coerentemente con il [contratto di sessione di Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html). Se l'header non viene fornito, viene generato un UUID casuale come fallback.
+
 :::caution[Organizzazione del codice]
 Probabilmente vorrai astrarre parte o tutto l'ID di sessione dal chiamante se gli utenti devono invocare il tuo agente direttamente. Ad esempio, potresti usare l'ID utente autenticato come parte dell'ID di sessione.
 
@@ -302,7 +303,7 @@ Per invocare un Agente in esecuzione localmente tramite il target `<your-agent-n
 
 ```bash
 curl -N -X POST http://localhost:8081/invocations \
-  -d '{"prompt": "what is 3 + 5?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
+  -d '{"message": "what is 3 + 5?"}' \
   -H "Content-Type: application/json"
 ```
 
@@ -337,7 +338,7 @@ Per l'Autenticazione Cognito, passa il Token di Accesso Cognito nell'header `Aut
 ```bash
 curl -N -X POST 'https://bedrock
 -agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
-  -d '{"prompt": "what is 3 + 5?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
+  -d '{"message": "what is 3 + 5?"}' \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer <access-token>"
 ```