e2e-chatbot-app-next: Expose backend /responses, /docs, and /openapi.json

[hayescode]

Problem

The e2e-chatbot-app-next frontend does not expose the API routes provided by its agent backend.

This conflicts with the Databricks documentation, which instructs users to query a deployed agent at POST /responses.

The OpenAI Agents SDK template also documents this exact URL in its curl examples.

Current behavior

The deployed app runs the chatbot frontend on the public port and configures API_PROXY with only the backend /invocations URL:

• agent-openai-agents-sdk/app.yaml
• agent-openai-agents-sdk/scripts/start_app.py

The frontend server proxies only /invocations:

• e2e-chatbot-app-next/server/src/index.ts

Requests for /responses, /docs, or /openapi.json therefore reach the SPA fallback instead of the backend:

• e2e-chatbot-app-next/server/src/index.ts

The backend already exposes its application through MLflow AgentServer:

• agent-openai-agents-sdk/agent_server/start_server.py

Reproduction

1. Deploy agent-openai-agents-sdk with its bundled chatbot frontend.

2. Send the documented request:

   curl --request POST \
     --url https://<app-url>.databricksapps.com/responses \
     --header "Authorization: Bearer <oauth-token>" \
     --header "Content-Type: application/json" \
     --data '{"input":[{"role":"user","content":"hi"}],"stream":true}'

3. The request is handled by the frontend rather than the backend Responses API.

4. Likewise, /docs and /openapi.json do not return the backend FastAPI documentation and schema.

Expected behavior

The public frontend server should proxy these same-origin routes to the agent backend:

Public route	Backend route
POST /responses	/responses
/docs	/docs
/openapi.json	/openapi.json

To preserve FastAPI's standard documentation surface, the frontend should also proxy:

Public route	Backend route	Purpose
/redoc	/redoc	FastAPI's alternative ReDoc API viewer
/docs/oauth2-redirect	/docs/oauth2-redirect	Swagger UI OAuth2 callback

/redoc is optional for basic API access, while /docs/oauth2-redirect is needed when the Swagger UI uses an OAuth2 authorization flow. Both are standard FastAPI routes rather than application-specific endpoints.

Both streaming and non-streaming /responses requests should work.

Suggested change

Extend the frontend's backend proxy support so it accepts a backend base URL and forwards /invocations, /responses, /docs, and /openapi.json.

Register these routes before the static-file and SPA fallback middleware. Preserve the request method, body, response status, relevant headers, and streaming response body.

Acceptance criteria

• POST /responses works through the deployed app URL.
• Streaming Responses API events are forwarded without buffering.
• Non-streaming Responses API responses are forwarded unchanged.
• /docs renders the backend API documentation.
• /openapi.json returns the backend OpenAPI schema.
• /redoc renders the backend ReDoc API reference.
• /docs/oauth2-redirect is forwarded for Swagger UI OAuth2 authentication.
• Existing chatbot and /invocations behavior remains unchanged.
• Automated coverage verifies routing and streaming behavior.
• The documented curl commands work against a deployed template app.

Risks and considerations

• Authentication and headers: The proxy must avoid forwarding hop-by-hop headers or leaking internal host information while preserving the Databricks identity headers required by the backend.
• Streaming: Buffering, missing backpressure handling, or failing to cancel the backend request after client disconnect could break SSE responses or waste resources.
• Route ordering: These routes must be registered before the SPA fallback, or they will continue returning frontend HTML.
• Backend URL configuration: API_PROXY currently contains the complete /invocations URL. Deriving other routes through string replacement would be fragile; a backend base URL would be safer.
• API exposure: /docs and /openapi.json expose the backend contract to users who can access the Databricks App. This should be intentional and remain protected by the app's existing authentication boundary.