feat: refactor Amazon Q module to use agentAPI

[harleylrn]

Title:

feat: complete amazon-q module v2.0.0 with comprehensive enhancements

Description:

Closes #240

This PR introduces a complete rewrite and enhancement of the amazon-q module, bringing it to version 2.0.0. The module now provides AgentAPI support.

Type of Change

• New module
• Bug fix
• Feature/enhancement
• Documentation
• Other

Module Information

Path: registry/coder/modules/amazon-q
New version: v2.0.0
Breaking change: [x] Yes [ ] No

Key Features & Enhancements

🚀 Core Functionality

• AgentAPI Support: Web and CLI app integration with health checks
• Amazon Q CLI Integration: Automatic installation and configuration of Amazon Q CLI
• MCP Integration: Model Context Protocol support for task reporting to Coder
• Authentication System: Tarball-based authentication with environment variable management

🛠️ Customization & Configuration

• Pre/Post Install Scripts: Support for custom setup and finalization scripts
• Agent Configuration: Templated agent config with tool and resource management
• Custom System Prompts: Configurable AI behavior and task reporting instructions
• Version Pinning: Support for specific Amazon Q CLI and AgentAPI versions

📚 Documentation & Testing

• Comprehensive README: Complete user guide with examples, configuration details, and troubleshooting
• Visual Documentation: Updated screenshots and interface examples
• Terraform Testing: Complete .tftest.hcl with 8 test cases (all passing)
• Registry Compliance: Full adherence to Coder Registry contributing guidelines

d## Breaking Changes

This is a major version update (v2.0.0) with breaking changes:

• Renamed variables names (Removed experimantal_ prefix)
• Updated AgentAPI integration method
• Modified default configuration structure

Testing & Validation

• Tests pass (terraform test - 8/8 tests passing)
• Code formatted (bun run fmt)
• Changes tested locally
• Registry compliance verified
• Documentation reviewed and updated

Related Issues

Closes #240 - Amazon Q module enhancement request

Additional Notes

• Module is now production-ready with professional quality code and documentation
• Full compliance with Coder Registry contributing guidelines
• Comprehensive test coverage ensures reliability
• Ready for registry submission and community use

Screenshots:

Screen.Recording.2025-08-25.at.09.50.09_github.mp4

Screen.Recording.2025-08-25.at.13.56.28_final.mp4

/claim #240

[bpmct]

Is this ready for review? I see its still marked as a draft PR @harleylrn

[harleylrn]

@bpmct Will be ready Monday 😄
WE want to verify it again internally first 😄

[keirans]

Hey Matey,
Have dropped some comments through this, let me know if you have any questions.

Appreciate the work, it's shaping up nicely.

[DevelopmentCats]

@harleylrn

I would try and keep both the main.test.ts as well as the new amazon-q.tftest.hcl since the CI will currently only run the typescript tests in the module dir's

[harleylrn]

OK @DevelopmentCats
Will add it back 😄

[35C4n0r]

@harleylrn
ran this with coder mcp server and I get this error

this is my agent.json

{
  "$schema": "https://raw.githubusercontent.com/aws/amazon-q-developer-cli/refs/heads/main/schemas/agent-v1.json",
  "name": "agent",
  "description": "This is an default agent config",
  "prompt": "You are a helpful Coding assistant. Aim to autonomously investigate and solve issues the user gives you and test your work, whenever possible.Avoid shortcuts like mocking tests. When you get stuck, you can ask the user but opt for autonomy.",
  "mcpServers": {
    "coder": {
      "command": "coder",
      "args": [
        "exp",
        "mcp",
        "server"
        ],
      "env": {
        "CODER_AGENT_TOKEN": "8ecb019e-74f9-4db1-ace7-7xx",
        "CODER_MCP_AI_AGENTAPI_URL": "http://localhost:3284",
        "CODER_MCP_APP_STATUS_SLUG": "amazonq",
        "CODER_AGENT_URL": "https://qwerty"
      },
      "timeout": 120000,
      "disabled": false
    }
  },
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash",
    "use_aws",
    "@coder",
    "knowledge"
  ],
  "toolAliases": {},
  "allowedTools": [
    "@coder",
    "fs_read"
  ],
  "resources": [
    "file://AmazonQ.md",
    "file://README.md",
    "file://.amazonq/rules/**/*.md",
    "file://AGENTS.md"
  ],
  "hooks": {},
  "toolsSettings": {},
  "useLegacyMcpJson": true
}

Amazon Q is having trouble responding right now: 
   0: Failed to send the request: unhandled error (ValidationException)
   1: unhandled error (ValidationException)
   2: service error
   3: unhandled error (ValidationException)
   4: Error { code: "ValidationException", message: "Improperly formed request.", aws_request_id: "16d65a48-0a4d-4a2c-856a-d2b42ed0ad80" }

Location:
   crates/chat-cli/src/cli/chat/mod.rs:1013

Backtrace omitted. Run with RUST_BACKTRACE=1 environment variable to display it.
Run with RUST_BACKTRACE=full to include source snippets.

[harleylrn]

@35C4n0r I had this issue before, then it disappeared....
Is your agent coming from the default agent? Or is your agent was configured using agent_config variable?
I don't see in your agent this parameter: --allowed-tools coder_report_task
It should be coming from this

registry/registry/coder/modules/amazon-q/scripts/install.sh

Line 144 in 00e6222

--args "exp,mcp,server,--allowed-tools,coder_report_task,--instructions,'$ARG_CODER_MCP_INSTRUCTIONS_DECODED'" \

line

[35C4n0r]

@harleylrn, I made some changes for the review on my local in which I removed --allowed-tools coder_report_task. Adding that flag fixes the issue.

@harleylrn any idea why this might be happening ?

I removed it after checking this (so that we allow all tools):

coder v2.25.1+3bf6a00

USAGE:
  coder exp mcp server [flags]

  Start the Coder MCP server.

OPTIONS:
      --ai-agentapi-url url, $CODER_MCP_AI_AGENTAPI_URL
          The URL of the AI AgentAPI, used to listen for status updates.

      --allowed-tools string-array, $CODER_MCP_ALLOWED_TOOLS
          Comma-separated list of allowed tools. If not specified, all tools are allowed.

      --app-status-slug string, $CODER_MCP_APP_STATUS_SLUG
          When reporting a task, the coder_app slug under which to report the task.

      --instructions string, $CODER_MCP_INSTRUCTIONS
          The instructions to pass to the MCP server.

———
Run `coder --help` for a list of global options.

cc @matifali

[harleylrn]

Don't have a clue 😄
Somehow it doesn't want to cooperate with AWS Q without this option... Even though it is added completely into the allowedTools in the agent config. I noticed also that if this flag is not passed to the Q, it doesn't see ANY tool that Coder MCP provides.

[35C4n0r]

@harleylrn here is a review in form of a patch (I know this isn't the best way to do this), if you have any comments/questions quote the change and ask :)

review_1.patch
review_2.patch

[35C4n0r]

PS: we would also need a PR in coder/agentapi to support AmazonQ.

[harleylrn]

I have number of comments here:

1. The pre and post scripts absolutely required for fine tuning. I found that this is actually have to be defined for any module,. even the simplest one such as git-clone
2. Why is the difference in the coder mcp allowed tools based on $ARG_REPORT_TASKS ? What is the harm to allow all the tools from coder regardless? Anyway it can be controlled by the @coder value in the allowedTools in the agent.json
3. The rest are cosmetic

Is it me to need to open the PR in coder/agentapi to support AmazonQ ?

[35C4n0r]

@harleylrn

1. The pre & post install script are still there, we just don't have to manually run it, we just need to provide it to agentapi module, and it takes care of running it.
2. We want to give user the option to run this module without tasks reporting.

added a new patch with some minor changes review_2.patch

Is it me to need to open the PR in coder/agentapi to support AmazonQ ?

Yes, we just need a PR similar to this: coder/agentapi#63

If the patch lgty, feel free to make a commit with it 👍🏻

[harleylrn]

Getting the following error with those changes @35C4n0r :

Looks like this error is coming from the removable of the line:

ARG_SERVER_PARAMETERS="-c /@${data.coder_workspace_owner.me.name}/${data.coder_workspace.me.name}.${var.agent_id}/apps/${local.app_slug}/chat"

with forced the AgentAPI to run with it.

Also the following comments:

1. Set the default var.working_dir to /home/coder to make it not required
2. It doesn't matter how many allowed-tools you are passing to the command line in the agent.json, it doesn't see any except the first one.

For the second one opened the new issue to the aws-q-developer-cli project aws/amazon-q-developer-cli#2753 and created the PR for the same: aws/amazon-q-developer-cli#2754

[harleylrn]

I tired to setup the CODER_WILDCARD_ACCESS_URL parameter, but it didn't help at all.
Still getting the error as in the screenshot

[matifali]

@michaelbrewer can you help test this? Thanks

[35C4n0r]

The changes lgtm 👍🏻

For the second one opened the new issue to the aws-q-developer-cli project aws/amazon-q-developer-cli#2753 and created the PR for the same: aws/amazon-q-developer-cli#2754

@harleylrn thanks for your PR.

Two things we need to keep track of here (can be done async after merging the PR)

• Track the above Bug & PR raised by @harleylrn
• Raise a PR in agentapi module for AmazonQ.

Just needs some changes in the readme, cc: @matifali

[harleylrn]

@35C4n0r Changed as you requested, even though I prefer it the other way around 😄