Python: Add hosting protocol helper surface

python/packages/hosting-responses/README.md

@@ -1,21 +1,51 @@
 # agent-framework-hosting-responses
 
-OpenAI Responses-shaped channel for `agent-framework-hosting`.
+OpenAI Responses-shaped helpers for app-owned Agent Framework hosting.
 
-Exposes a single `POST /responses` endpoint that accepts the OpenAI
-Responses API request body and returns either a Responses-shaped JSON
-body or a Server-Sent-Events stream when `stream=True`.
+This package provides the Responses-specific conversion layer:
+
+- `responses_to_run(...)` — convert a Responses request body into Agent
+  Framework run values.
+- `responses_session_id(...)` — extract a prior `resp_*` response id or
+  `conv_*` conversation id from the request body when present.
+- `create_response_id(...)` — mint a Responses-shaped response id.
+- `responses_from_run(...)` — convert an `AgentResponse` into a
+  Responses-compatible JSON payload.
+- `responses_stream_from_run(...)` — convert an Agent Framework
+  `ResponseStream` into Responses-compatible SSE events.
+
+FastAPI/Starlette/Django/Azure Functions code owns route registration,
+authentication, status codes, response construction, and background work.
 
 ```python
-from agent_framework.openai import OpenAIChatClient
-from agent_framework_hosting import AgentFrameworkHost
-from agent_framework_hosting_responses import ResponsesChannel
+from agent_framework_hosting import AgentState
+from agent_framework_hosting_responses import (
+    create_response_id,
+    responses_from_run,
+    responses_session_id,
+    responses_to_run,
+)
+from fastapi import Body, FastAPI
+from fastapi.responses import JSONResponse
+
+app = FastAPI()
+state = AgentState(agent)
 
-agent = OpenAIChatClient().as_agent(name="Assistant")
 
-host = AgentFrameworkHost(target=agent, channels=[ResponsesChannel()])
-host.serve(port=8000)
+@app.post("/responses")
+async def responses(body: dict = Body(...)) -> JSONResponse:
+    run = responses_to_run(body)
+    session_id = responses_session_id(body)
+    response_id = create_response_id()
+    session = await state.get_or_create_session(session_id or response_id)
+    result = await (await state.get_target()).run(
+        run["messages"],
+        session=session,
+        options=run["options"],
+    )
+    await state.set_session(response_id, session)
+    return JSONResponse(responses_from_run(result, response_id=response_id, session_id=session_id))
 ```
 
-The base host plumbing lives in
+The base execution-state helpers live in
 [`agent-framework-hosting`](https://pypi.org/project/agent-framework-hosting/).

python/packages/hosting-responses/agent_framework_hosting_responses/__init__.py

@@ -6,9 +6,14 @@
 
 from ._channel import ResponsesChannel
 from ._parsing import (
+    create_response_id,
     messages_from_responses_input,
     parse_responses_identity,
     parse_responses_request,
+    responses_from_run,
+    responses_session_id,
+    responses_stream_from_run,
+    responses_to_run,
 )
 
 try:
@@ -19,7 +24,12 @@
 __all__ = [
     "ResponsesChannel",
     "__version__",
+    "create_response_id",
     "messages_from_responses_input",
     "parse_responses_identity",
     "parse_responses_request",
+    "responses_from_run",
+    "responses_session_id",
+    "responses_stream_from_run",
+    "responses_to_run",
 ]