GCP deployment guide uses incorrect approach for Bot Framework messaging - needs CloudAdapter implementation

[sellakumaran]

Problem

The current GCP deployment documentation at https://learn.microsoft.com/en-us/microsoft-agent-365/developer/deploy-agent-gcp#create-project provides a basic Express.js implementation that doesn't properly handle Bot Framework token acquisition and response routing.

The documented sample code uses a simple Express endpoint that returns a reply object directly:

app.post("/api/messages", (req, res) => {
  console.log("Received activity:", JSON.stringify(req.body, null, 2));
  // Echo activity
  const reply = {
    type: "message",
    text: `You said: ${req.body?.text}`
  };
  res.status(200).send(reply);
});

This approach has led partners (including DBS and others) to implement custom getBotFrameworkToken() functions and manual token management, which is unnecessary and error-prone.

Expected Behavior

The documentation should demonstrate the correct pattern using CloudAdapter from @microsoft/agents-hosting, which handles Bot Framework token acquisition and reply routing automatically.

Recommended Solution

Update the GCP deployment documentation to align with the patterns used in our official samples:

Entry point pattern (from nodejs/openai/sample-agent/src/index.ts):

server.post('/api/messages', (req: Request, res: Response) => {
  const adapter = agentApplication.adapter as CloudAdapter;
  adapter.process(req, res, async (context) => {
    await agentApplication.run(context);
  });
});

Sending responses (from nodejs/openai/sample-agent/src/agent.ts):

await turnContext.sendActivity(response);

Key Points to Include in Documentation

1. CloudAdapter reads the serviceUrl from the incoming activity
2. It handles Bot Framework token acquisition internally
3. It routes replies back to Teams without custom token logic
4. @microsoft/agents-hosting is platform-agnostic and works on any platform (Azure, GCP, AWS)
5. No manual token management is required

Impact

• Partners are implementing workarounds with custom token management
• Increased support burden due to incorrect implementation patterns
• Security risks from improper token handling
• Inconsistency between documentation and official samples

Related Resources

• Official samples: https://github.com/microsoft/Agent365-samples
• Correct implementation reference: nodejs/openai/sample-agent
• Current problematic documentation: https://learn.microsoft.com/en-us/microsoft-agent-365/developer/deploy-agent-gcp#create-project

Customer Feedback Source

Multiple partners (DBS, Wajeed Shaikh) have reported following the current documentation and needing to implement custom token management solutions.

[github-actions]

[AUTO-TRIAGE] Team Assistant Triage

This issue has been automatically analyzed and triaged.

AI Decision Reasoning: Type: Classified as 'documentation' because the issue highlights incorrect implementation guidance in the GCP deployment documentation for Bot Framework messaging.
Priority: Elevated to P1 due to security concern: Security keywords detected: security
Copilot: Security issues require human review and should not be auto-fixed
Assignment: Security issue assigned to security lead. Security keywords detected: security
Labels: Applied labels documentation, P1, security based on issue type and priority

Labels and assignee have been applied based on this analysis.

[github-actions]

[AUTO-TRIAGE] Results

Classification: documentation
Priority: P1
Confidence: 95.0%

Recommended Assignee: @sellakumaran

Analysis:
type rationale: Classified as 'documentation' because the issue highlights incorrect implementation guidance in the GCP deployment documentation for Bot Framework messaging.

priority rationale: Elevated to P1 due to security concern: Security keywords detected: security

copilot rationale: Security issues require human review and should not be auto-fixed

assignment rationale: Security issue assigned to security lead. Security keywords detected: security

labels rationale: Applied labels documentation, P1, security based on issue type and priority

[SUGGESTION] Suggested Approach

1. Update the GCP deployment documentation in the docs directory to replace the current Express.js implementation with the correct CloudAdapter pattern. Use the sample code provided in the issue description and align it with the patterns from the official samples repository (e.g., nodejs/openai/sample-agent/src/index.ts).
2. Add a new section in the GCP deployment guide to explain how CloudAdapter simplifies token acquisition and response routing. Highlight its ability to read the serviceUrl and manage Bot Framework tokens internally, reducing the need for custom implementations.
3. Include a complete working example of the updated GCP deployment code in the documentation, ensuring it covers both the entry point (server.post) and response handling (turnContext.sendActivity). Reference the @microsoft/agents-hosting package explicitly and ensure the example is compatible with the latest version.
4. Verify the updated documentation by creating an integration test in the autoTriage/tests/integration directory to simulate a GCP deployment using the new CloudAdapter implementation. This will help ensure the updated guide works as expected.
5. Add a note in the documentation to deprecate the old Express.js implementation and recommend all users migrate to the CloudAdapter approach. Link to the official samples repository for further reference and provide troubleshooting tips for common deployment issues.

---

Generated by TeamAssistant Auto-Triage powered by GitHub Models