██FR█████ █INTELL███████████

Amazon Q Developer Custom Agents


This content originally appeared on DEV Community and was authored by 8P Inc.

หลายคนที่ได้ลองใช้ Amazon Q Developer น่าจะหงุดหงิดของ /profile เพราะมันดันไม่สามารถ custom พวก MCP configuration ได้ และไม่สามารถ set trust tools ตามแต่ละ profile ได้
ตอนนี้ AWS เลยทำการ rebrand /profile ไปเป็น feature ใหม่ที่เรียกว่า custom agents

คราวนี้เรามาดูกันครับว่า custom agents มีอะไรให้เราเล่นบ้าง

Migrate

เริ่มจากการ migrate ก่อน ปกติ Q cli จะถามว่าเราจะ upgrade ไหม แต่ถ้าไม่ถาม หรือว่าเรา say no ไปก็ run command นี้ เพื่อ migrate ได้

q agent migrate --force

ถ้าใครอยากลงลึกเรียนเชิญ -> Migrate Profiles to Agents

Customize Agents

หลังจากที่ migrate แล้ว profile ที่เรา set ไว้มันจะกลายเป็น agent ให้เราโดยอัตโนมัติ โดยกลายเป็น json configuration file ใน path ~/.aws/amazonq/cli-agents/<NAME>.json

AWS มี plan ที่จะเพิ่ม sub command /agent edit <NAME> ให้ แต่ ณ วันที่เขียน blog นี้ยังไม่มี แต่เราสามารถ edit file นี้ได้ตรงๆ ผ่าน ide ได้ตามปกติ

ที่นี้มาดูหน้่าตาของ configuration file ( สามารถพิมพ์ /agent schema เพื่อดู schema เต็มๆ ของ config ได้ )

{
  "name": "<NAME>",
  "description": "",
  "prompt": null,
  "mcpServers": {},
  "tools": [
    "*"
  ],
  "toolAliases": {},
  "allowedTools": [
    "fs_read"
  ],
  "resources": [
    "file://AmazonQ.md",
    "file://README.md",
    "file://.amazonq/rules/**/*.md"
  ],
  "hooks": {},
  "toolsSettings": {},
  "useLegacyMcpJson": true
}
  • name คือ ชื่อของ custom agent ควรตรงกับ ชื่อ file เพื่อความไม่สับสน โดย Q cli จะอ้างอิงชื่อ custom agent จากในส่วนนี้
  • description คือ คำอธิายคร่าวๆ ของ custom agent นี้
  • prompt คือที่ใส่ system prompt ของ custom agent นี้ แต่ค่านี้ยังไม่ได้ implement
  • mcpServers คือ ที่ configure mcp server ที่ agent นี้จะ start ขึ้นมาพร้อมกับ custom agent
  • tools ใช้ระบุ tools ต่างๆ ที่ custom agent นี้สามารถใช้ได้ สามารถระบุได้ทั้ง builtin tools และ tools จาก mcp server
  • toolAliases ใช้ตั้งชื่อ tools ที่มีอยู่แล้วใหม่ ให้เป็นแบบที่เข้าใจง่ายขึ้น หรือ จำง่ายขึ้น
  • allowedTools ใช้ระบุว่า เมื่อ Q cli ถูก start ขึ้นมาให้ trust tools ไหนได้เลย
    • โดยสามารถ allow ได้ทั้งแบบ
      • ระบุ built-in tools -> fs_read
      • ทั้ง mcp server -> @server_name
      • เฉพาะบาง tools ใน mcp server -> @server_name/tool_name
      • ทั้งหมด -> *
      • builtin ทั้งหมด -> @builtin 
   {
     "allowedTools": [
       "fs_read",
       "@git/git_status",
       "@fetch"
     ]
   }
  • resources ใช้ระบุถึง context file ของ custom agent นั้นๆ เป็น concept เดียวกับ /context ที่ใช้ร่วมกับ /profile
  • hooks เป็นที่ที่เราสามารถ define ได้ว่า ใน event เหล่านี้ จะให้ Q cli ทำอะไร โดย ตอนนี้มี 2 events คือ
    • agentSpawn: ตอนที่ Q cli ถูก start
    • userPromptSubmit: ตอนที่เรา submit prompt ให้ Q cli 
{
  "hooks": {
    "agentSpawn": [
      {
        "command": "git status",
      }
    ],
    "userPromptSubmit": [
      {
        "command": "ls -la",
      }
    ]
  }
}
  • toolsSettings ใช้ define configuration ต่างๆ ของ builtin tools เช่น 
   {
     "toolsSettings": {
       "fs_write": {
         "allowedPaths": ["src/**", "tests/**"]
       },
       "execute_bash": {
         "allowedCommands": ["git status", "npm test"],
         "allowReadOnly": true
       },
       "use_aws": {
         "allowedServices": ["s3", "lambda", "ec2"]
       }
     }
   }
  • useLegacyMcpJson ระบุว่าจะให้ include legacy global MCP configuration file (~/.aws/amazonq/mcp.json) เข้ามาด้วยไหมตอน Q cli ถุก start

สามารถดูเพิ่มเติมได้จาก Agent Configuration Format

Validate Agent Configuration 

q agent validate --path ./my-agent.json

ถ้า syntax ผิดจะเป็นประมาณนี้

syntax-error

แต่ถ้าถูกจะไม่มีอะไร print ออกมา และ exit 0

good-to-go

Use Custom Agent

เราสามารถ lists agent ทั้งหมดที่เรามีได้โดย

q agent list

[default]> /agent list

จากนั้นเรียกใช้ custom agent ดังนี้

q chat --agent <NAME>

ในอนาคต เราจะสามารถ switch custom agent ได้ด้วย /agent use <NAME> ซึ่งเป็น feature ที่กำลัง develop อยู่

Set Default Agent

เมื่อเราสร้าง custom agent แล้วสามารถ set ให้มันเป็น ค่า default ได้โดย

q agent set-default --name <NAME>

/agent set-default --name <NAME>

จากนั้นเราสามารถเรียกใช้ custom agent ได้ โดยการเรียก q หรือ q chat ได้โดยไม่ต้องระบุชื่อ custom agent แล้ว

ถ้าเราไม่ได้ set default agent ไว้ Q cli จะใช้งาน builtin default agent ในการทำงาน เช่นเดียวกันถ้า configuration ของ custom agent เราผิด เวลาเรา start Q cli มันก็จะ fail over มาใช้งาน builtin default agent เหมือนกัน

Type of Custom Agent Configuration

มีอยู่ 2 แบบ ดังนี้

  • Local custom agent (Workspace-specific)
    • Path: {current_working_directory}/.amazonq/cli-agents/
    • Scope: จะใช้ได้ก็ต่อเมื่อ start Q cli ใน {current_working_directory}
    • Use Case: Project-specific agents หรือ team-shared configurations
    • Example: 
my-project/
├── .amazonq/
│   └── cli-agents/
│       ├── dev-agent.json
│       ├── aws-specialist.json
│       └── code-reviewer.json
├── src/
│   └── main.py
└── README.md
  • Global custom agent
    • Path: ~/.aws/amazonq/cli-agents/
    • Scope: start Q cli ได้ทุกที่
    • Use Case: agents ส่วนตัว หรือ ใช้เป็น general-purpose assistants
    • Example 
~/.aws/amazonq/cli-agents/
├── general-assistant.json
├── documentation-writer.json
├── security-analyst.json
└── devops-automation.json

ถ้าเราอยู่ที่ {current_working_directory} แล้ว list agents จะเห็นแบบนี้

> q agent list
general-assistant        /Users/demo/.aws/amazonq/cli-agents
documentation-writer     /Users/demo/.aws/amazonq/cli-agents
security-analyst         /Users/demo/.aws/amazonq/cli-agents
devops-automation        /Users/demo/.aws/amazonq/cli-agents
dev-agent                /Users/demo/my-project/.amazonq/cli-agents
aws-specialist           /Users/demo/my-project/.amazonq/cli-agents
code-reviewer            /Users/demo/my-project/.amazonq/cli-agents

[dev-agent] > /agent list

  general-assistant   
  documentation-writer
  security-analyst    
  devops-automation               
* dev-agent           
  aws-specialist      
  code-reviewer


This content originally appeared on DEV Community and was authored by 8P Inc.