AWS Thai Blog

ปรับแต่ง Amazon Q Developer CLI ด้วย Custom Agents

Amazon Q Developer ถึงแม้จะมีคำว่า developer อยู่ในชื่อ แต่ไม่ได้จำกัดให้ใช้เฉพาะกลุ่ม programmers เท่านั้น เราเชื่อว่าทุกคน develop something และ Amazon Q Developer จะเข้าไปช่วยคุณ develop สิ่งเหล่านั้นให้สำเร็จ

หากคุณเคยใช้งาน Amazon Q Developer แล้ว คุณอาจเคยปรับแต่งให้ Amazon Q Developer CLI ตรงกับความต้องการ ทั้งการใช้ profile, context หรือ MCP เพื่อทำให้ประสบการณ์การใช้งานของผู้ใช้งานดีขึ้น และเพื่อให้ Amazon Q Developer เป็นผู้ช่วยที่เข้าใจงานของคุณได้ดียิ่งขึ้น AWS ได้ออกฟีเจอร์ใหม่ขึ้นมาแทน profile แล้วนั่นคือ Custom Agents

โดย concept ของ Custom Agents จะเป็นการรวม configuration ต่างๆ ที่อยู่ในหลายๆ ที่ มารวมกันเป็น JSON file 1 file สำหรับ 1 custom agent ด้วยวิธีนี้จะทำให้ผู้ใช้งานสามารถปรับแต่งได้ง่ายขึ้น แชร์กับทีมได้สะดวกขึ้น และสามารถทำ version control ผ่าน Git ได้ ทำให้การทำงานร่วมกันในทีมและการดูแลรักษา configuration เป็นเรื่องง่าย เมื่อ agent ถูกเรียกใช้งาน configuration ต่างๆ ก็จะถูกดึงเข้ามาทั้งหมด ทำให้ agent พร้อมใช้งานตามที่เรา configure ไว้ โดยที่เราไม่ต้องไปปรับอะไรอีก

สิ่งที่ควรรู้ก่อนเริ่มต้น

ความรู้พื้นฐานที่จำเป็น

  • JSON: รูปแบบไฟล์สำหรับเก็บข้อมูล (ไม่ต้องเป็นผู้เชี่ยวชาญ แค่เข้าใจโครงสร้างพื้นฐาน)
  • Command Line: การใช้ terminal หรือ command prompt เบื้องต้น
  • Amazon Q Developer CLI: ติดตั้งและใช้งานเบื้องต้นได้แล้ว

คำศัพท์ที่ควรเข้าใจ

  • Agent: Amazon Q Developer ที่ปรับแต่งเฉพาะงาน
  • Tools: เครื่องมือที่ AI สามารถใช้ได้ (เช่น อ่านไฟล์, รัน command)
  • Context: ข้อมูลพื้นหลังที่ AI ใช้ในการตอบคำถาม
  • Permissions: สิทธิ์ในการใช้เครื่องมือต่างๆ

หากคุณเคยใช้ profile ในเวอร์ชันก่อนหน้า คุณอาจสงสัยว่า Custom Agents แตกต่างอย่างไร?

  • Profile เดิม ทำงานแบบแยกส่วน – คุณต้องตั้งค่า tools, permissions, และ context แยกกันในหลายที่ และต้องจำว่าตั้งค่าอะไรไว้ที่ไหน
  • Custom Agents รวมทุกอย่างเข้าด้วยกัน – ไฟล์ JSON เดียวมีครบทั้ง AI personality, tools, permissions, context files, และ external connections ทำให้จัดการง่ายกว่าและแชร์กับทีมได้สะดวก

อาจนึกภาพง่ายๆ ว่า profile เหมือนการมีเครื่องมือกระจัดกระจายในกล่องหลายใบ ส่วน Custom Agents เหมือนกระเป๋าเครื่องมือที่จัดระเบียบดี ทุกอย่างอยู่ที่เดียว พร้อมใช้งาน

เริ่มต้นใน 5 นาที

สร้าง Agent แรกของคุณ

  1. สร้างไฟล์: mkdir -p .amazonq/cli-agents && touch .amazonq/cli-agents/my-first-agent.json
  2. คัดลอกโค้ด: ใช้ตัวอย่างพื้นฐานด้านล่าง
  3. ทดสอบ: q agent validate --path .amazonq/cli-agents/my-first-agent.json
  4. ใช้งาน: q chat --agent my-first-agent
{
  "name": "my-first-agent",
  "description": "Agent แรกของฉัน",
  "tools": ["fs_read"],
  "allowedTools": ["fs_read"]
}

เคล็ดลับสำหรับมือใหม่: หากยังไม่คุ้นเคยกับ JSON ให้เริ่มจากการคัดลอกตัวอย่างแล้วค่อยๆ ปรับแต่ง อย่าลืมใช้ q agent validate --path /path/to/agent.json เพื่อตรวจสอบ syntax

สิ่งที่คุณจะได้จาก Custom Agents

Custom Agents ช่วยให้คุณสร้าง AI เฉพาะทางที่ออกแบบมาสำหรับงานของคุณโดยเฉพาะ แทนที่จะใช้ AI แบบ one-size-fits-all คุณสามารถสร้าง agent แยกกันสำหรับ frontend development, backend architecture, DevOps operations, Document Writer หรือแม้กระทั่ง content writer ที่มีความเชี่ยวชาญที่ต้องการ

การที่เราสามารถสร้าง Agent ที่มีความเชี่ยวชาญเฉพาะทาง นอกจากจะช่วยเพิ่มประสิทธิภาพในการทำงานแล้ว เรายังสามารถกำหนดให้ agent โหลดเอกสารในโปรเจคเข้ามาเป็น context ทำให้ AI เข้าใจบริบทของงานได้ทันที โดยไม่ต้องอธิบายซ้ำทุกครั้ง นอกจากนี้ยังสามารถกำหนด permission ให้กับ tools เพื่อให้ agent สามารถเรียกใช้ได้เลย โดยไม่ต้องขออนุญาต หรือ ห้ามใช้ไปเลย จะได้ไม่ต้องมาขออนุญาตให้เสียเวลา

ตัวอย่างการใช้งาน

  • สำหรับ Full-stack Developer คุณสามารถสร้าง agent ที่รู้จัก React, TypeScript, และ AWS Lambda พร้อมทั้งเข้าใจเอกสาร API และ coding standards ของทีม เมื่อคุณถามเกี่ยวกับการ optimize React components หรือการ deploy Lambda functions agent จะให้คำแนะนำที่สอดคล้องกับ architecture และแนวทางของโปรเจคโดยอัตโนมัติ
  • สำหรับ DevOps Engineer คุณสามารถสร้าง agent ที่เชี่ยวชาญใน Terraform และ CloudFormation พร้อมเชื่อมต่อกับ AWS services และ monitoring tools ต่างๆ การถามเกี่ยวกับ infrastructure scaling หรือ troubleshooting จะได้รับคำตอบที่เข้าใจ environment และ constraints ของระบบจริง
  • สำหรับ Product Manager คุณสามารถสร้าง agent ที่เข้าใจบริบทของ product รวมถึงข้อจำกัดต่างๆ ทำให้สามารถนำความต้องการ แปลออกมาเป็น requirements หรือเสนอแนะการตัดสินใจทางธุรกิจ ได้อย่างตรงกับความต้องการของผู้ใช้งาน
  • สำหรับ Content Writer คุณสามารถสร้าง agent ที่เข้าใจ style การเขียน รวมทั้ง preferences ต่างๆ และด้วยความสามารถของ MCP servers ทำให้ agent สามารถ research ข้อมูลเพิ่มเติม ทำให้ได้ content ที่ตรงกับที่ผู้ใช้งานต้องการ

เมื่อเข้าใจประโยชน์ของ Custom Agents แล้ว มาดูกันว่าระบบนี้ทำงานอย่างไร

Custom Agents ทำงานอย่างไร

ขั้นตอนการทำงานของ Custom Agents เมื่อถูก start

เมื่อคุณรัน q chat --agent my-agent ระบบจะ:

  1. โหลด Configuration ทำการค้นหาไฟล์ my-agent.json ในโปรเจค (.amazonq/cli-agents/) ก่อน หากไม่พบ จะค้นหาใน global directory (~/.aws/amazonq/cli-agents/) จากนั้นอ่านและตรวจสอบ JSON syntax
  2. เตรียม AI Personality โดยโหลด prompt เป็น system instruction เพื่อกำหนดบุคลิกภาพและความเชี่ยวชาญของ AI จากนั้น ตั้งค่าพฤติกรรมการตอบคำถาม
  3. เตรียม Tools และ Permissions โดยโหลดรายการ tools ที่ agent สามารถใช้ได้ แล้วจึงตั้งค่า allowedTools สำหรับการใช้งานโดยไม่ต้องขออนุญาต จากนั้นใช้ toolsSettings เพื่อจำกัดขอบเขตการทำงาน
  4. โหลด Context อ่านไฟล์ทั้งหมดใน resources แล้วแปลงเป็น context ที่ AI สามารถเข้าใจได้ เพื่อเก็บไว้ในหน่วยความจำสำหรับการอ้างอิง
  5. เชื่อมต่อ External Services โดย start MCP servers ตาม configuration ที่กำหนดไว้ จากนั้นทดสอบการเชื่อมต่อ และ เตรียม tools จาก external services
  6. รัน Hooks รัน agentSpawn hooks เพื่อเก็บข้อมูลเริ่มต้น เก็บผลลัพธ์เป็น context เพิ่มเติม
  7. เข้าสู่สถานะพร้อมใช้งาน โดย Agent พร้อมตอบคำถามด้วยความรู้และเครื่องมือที่กำหนดไว้ โดยทุกครั้งที่คุณส่งข้อความ จะรัน userPromptSubmit hooks ก่อนตอบ

ขั้นตอนการทำงานของ Custom Agents เมื่อได้รับคำสั่ง

เมื่อคุณถาม “ช่วยดู AWS Lambda functions ในโปรเจคนี้หน่อย” สิ่งที่เกิดขึ้นคือ

  1. Agent ตรวจสอบ context จากไฟล์ที่โหลดไว้ (เช่น package.json, README.md)
  2. รัน hooks เพื่อดูสถานะปัจจุบัน (เช่น git status)
  3. ใช้ AWS CLI (ถ้าอยู่ใน allowedTools) เพื่อ list functions
  4. ค้นหาข้อมูลเพิ่มเติม ผ่าน MCP servers (เช่น AWS documentation)
  5. รวบรวมคำตอบ ที่เข้าใจบริบทของโปรเจคและให้คำแนะนำที่เฉพาะเจาะจง

ตัวอย่างการกำหนดค่า Custom Agent

{
  "name": "my-helper",
  "description": "AI assistant for my project",
  "tools": ["fs_read", "fs_write"],
  "allowedTools": ["fs_read"]
}

ใน configuration นี้ ระบุว่า:

  • Agent มีชื่อ “my-helper“
  • สามารถใช้ tools 2 ตัว: การอ่านไฟล์ (fs_read) และการเขียนไฟล์ (fs_write)
  • อนุญาตให้ใช้การอ่านไฟล์โดยไม่ต้องขอ permission (allowedTools)

เพิ่มเติม: สามารถดู​ JSON schema ของ custom agent ได้จาก chat command ใน Amazon Q Developer /agent schema หรือ ใน shell echo '/agent schema' | q chat --no-interactive

ตัวอย่างข้างต้นเป็นเพียงพื้นฐานเท่านั้น ในความเป็นจริง Custom Agents มีความสามารถมากกว่านั้น มาดูองค์ประกอบต่างๆ ที่ทำให้ agent ของคุณทรงพลังขึ้นกัน

องค์ประกอบสำคัญของการกำหนดค่า Agent

  1. ข้อมูลพื้นฐาน 
    {
  "name": "aws-expert",
  "description": "AWS infrastructure specialist"
}
    • name – ชื่อของ agent (จำเป็น – ใช้ในการระบุตัวตนของ agent)
    • description – คำอธิบายสำหรับการอ้างอิง
  2. การกำหนด System Prompt 
    {
  "prompt": "You are an experienced AWS expert with deep knowledge of infrastructure and best practices"
}
    • prompt – ทำหน้าที่เป็น “system prompt” ที่กำหนดบุคลิกภาพและความเชี่ยวชาญของ AI
  3. การเลือก Tools 
    {
  "tools": ["fs_read", "fs_write", "execute_bash", "use_aws"]
}
    • Builtin tools ที่ agent สามารถใช้งานได้มีดังนี้:
      • fs_read – การอ่านไฟล์และโฟลเดอร์
      • fs_write – การสร้างและแก้ไขไฟล์
      • execute_bash – การรัน command line
      • use_aws – การเรียกใช้ AWS CLI
      • report_issue – การรายงานปัญหาไปยัง GitHub
    • Tools ที่มีใน MCP servers สามารถ configure ได้ทั้ง
      • @mcp-server-name สำหรับ เลือก tools ทั้งหมดที่มีให้ใช้งานใน MCP Server นั้นๆ
      • @mcp-server-name/tool-name สำหรับการระบุ tool ใน MCP Server ไปเลย
  4. การกำหนดสิทธิ์ Tools 
    {
  "allowedTools": ["fs_read", "use_aws"]
}
    • allowedTools – tools ที่สามารถใช้งานได้โดยไม่ต้องขอ permission ทุกครั้ง (trusted tools) ช่วยให้การทำงานมีประสิทธิภาพมากขึ้น
  5. การตั้งค่า Tools 
    {
  "toolsSettings": {
    "use_aws": {
      "allowedServices": ["s3", "lambda", "ec2"]
    },
    "fs_write": {
      "allowedPaths": ["src/**", "docs/**", "*.md"]
    }
  }
}
    • toolsSettings – การตั้งค่าเฉพาะสำหรับแต่ละ tool เช่น ระบุ AWS services, path หรือ shell command ที่สามารถใช้งานได้ และ ที่ห้ามใช้
  6. การโหลดไฟล์ Context 
    {
  "resources": [
    "file://README.md",
    "file://docs/**/*.md",
    "file://package.json"
  ]
}
    • resources – ไฟล์ที่จะโหลดเป็น context โดยอัตโนมัติ เช่น เอกสารโปรเจค, ไฟล์กำหนดค่าต่างๆ โดย ต้องขึ้นต้นด้วย file:// และสามารถใช้ pattern ** สำหรับหลายไฟล์
  7.  Hooks: การรัน Commands อัตโนมัติ 
    {
  "hooks": {
    "agentSpawn": [
      {"command": "git status"},
      {"command": "aws sts get-caller-identity"}
    ],
    "userPromptSubmit": [
      {"command": "git diff --name-only HEAD~1"}
    ]
  }
}
    • agentSpawn – รันเมื่อ agent เริ่มทำงาน (ตรวจสอบ git status และ AWS account)
    • userPromptSubmit – รันทุกครั้งที่ผู้ใช้ส่ง message (ดูไฟล์ที่มีการเปลี่ยนแปลง)
  8. MCP: การเชื่อมต่อเครื่องมือภายนอก 
    {
  "mcpServers": {
    "awslabs.aws-documentation-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_DOCUMENTATION_PARTITION": "aws"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
  9. Tool Aliases: การจัดการชื่อ Tools 
    {
  "toolAliases": {
    "@awslabs.aws-documentation-mcp-server/search_documentation": "search_docs",
    "@awslabs.aws-documentation-mcp-server/read_documentation": "read_docs"
  }
}
    • แทนที่จะเรียก @awslabs.aws-documentation-mcp-server/search_documentation สามารถเรียก search_docs ได้โดยตรง เป็นการแก้ไขปัญหา naming conflicts เมื่อมี tools หลายตัวที่มีชื่อซ้ำกัน

เพิ่มเติม: สามารถศึกษา parameters ทั้งหมดได้จาก Agent Format

ตัวอย่าง Custom Agents

Content Writer

{
  "name": "content-specialist",
  "description": "Content writer with brand voice and research capabilities",
  "prompt": "You are an experienced content writer who understands brand voice, SEO best practices, and audience engagement. Always maintain consistent tone and style.",
  "tools": ["fs_read", "fs_write"],
  "allowedTools": ["fs_read"],
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["content/**", "blog/**", "*.md"]
    }
  },
  "resources": [
    "file://brand-guidelines.md",
    "file://content-style-guide.md",
    "file://target-audience.md"
  ],
  "mcpServers": {
    "research-tools": {
      "command": "research-mcp-server"
    }
  }
}

Agent นี้มีคุณสมบัติเป็น ผู้เชี่ยวชาญในการเขียน content ให้สอดคล้องกับ brand voice และ เหมาะกับ target audience โดยสามารถค้นคว้าข้อมูลผ่าน research tools และ ตรวจสอบ style guide ได้โดยอัตโนมัติ

AWS Specialist (Technical)

{
  "name": "aws-specialist",
  "description": "AWS infrastructure and development specialist",
  "prompt": "You are an experienced AWS expert with deep knowledge of CloudFormation, Lambda, S3 and best practices",
  "tools": ["fs_read", "fs_write", "execute_bash", "use_aws"],
  "allowedTools": ["fs_read", "use_aws"],
  "toolsSettings": {
    "use_aws": {
      "allowedServices": ["s3", "lambda", "cloudformation", "ec2", "iam"]
    },
    "fs_write": {
      "allowedPaths": ["infrastructure/**", "*.yaml", "*.json"]
    }
  },
  "resources": [
    "file://README.md",
    "file://infrastructure/**/*.yaml"
  ]
}

Agent นี้มีคุณสมบัติเป็น ผู้เชี่ยวชาญด้าน AWS โดย จัดการ AWS infrastructure ด้วย best practices, เขียนและแก้ไข CloudFormation templates พร้อมทั้ง ตรวจสอบ AWS resources และ configurations และ ให้คำแนะนำเฉพาะ AWS services ที่ใช้ในโปรเจค ได้ด้วย

หลังจากเข้าใจการกำหนดค่าแล้ว มาดูวิธีนำไปใช้งานจริงในโปรเจคของคุณ

การใช้งานในทางปฏิบัติ

ที่เก็บไฟล์ Configuration ของ Agent

Agent config จะถูกเก็บตามลำดับความสำคัญดังนี้:

  • .amazonq/cli-agents/ ← สำหรับโปรเจคนี้เท่านั้น (ความสำคัญสูงสุด)
  • ~/.aws/amazonq/cli-agents/ ← Global agents

เมื่อเรียกใช้ agent ระบบจะค้นหาจากโปรเจค (directory ปัจจุบันที่เราอยู่) ก่อน หากไม่พบจึงค้นหาจาก global

การสร้าง Agent ใหม่

สามารถสร้างได้ 3 วิธี

  • วิธีที่ 1: สร้างผ่าน CLI command
    q agent create --name my-agent
  • วิธีที่ 2: สร้างผ่าน chat session
    q chat
    > /agent create --name my-agent
  • วิธีที่ 3: สร้างไฟล์ด้วยตนเอง
    • Workspace-specific agent 
      mkdir -p .amazonq/cli-agents
cat > .amazonq/cli-agents/my-agent.json << 'EOF'
{
  "name": "my-agent",
  "description": "Agent for this project",
  "tools": ["fs_read", "fs_write"],
  "allowedTools": ["fs_read"]
}
EOF
    • Global agent 
      mkdir -p ~/.aws/amazonq/cli-agents
cat > ~/.aws/amazonq/cli-agents/global-agent.json << 'EOF'
{
  "name": "global-agent",
  "description": "Agent for global",
  "tools": ["fs_read", "fs_write"],
  "allowedTools": ["fs_read"]
}
EOF

การใช้งาน Agent

  • เริ่ม chat ด้วย agent ที่เลือก
    q chat --agent my-agent
  • ใช้ default agent
    q chat

การจัดการ Agent ใน Chat

  • แสดงรายการ agents ทั้งหมด
    > /agent list
  • แสดง JSON schema สำหรับ agent config
    > /agent schema
  • ตั้งค่าให้ custom agent ที่ระบุเป็น default agent
    > /agent set-default --name my-agent
  • เปลี่ยน custom agent
    > /agent swap my-agent

การจัดการ Agent ใน Shell

  • แสดงรายการ agents ทั้งหมด
    q agent list
  • valiate JSON config ของ agent
    q agent validate --path /path/to/config.json
  • ตั้งค่าให้ custom agent ที่ระบุเป็น default agent
    q agent set-default --name my-agent

เพิ่มเติม: เพื่อความเข้าใจที่มากขึ้น และ เห็นตัวอย่างของ multi-agent collaboration สามารถทำตาม workshop Lab7 – Create Specialized Agents with Custom Agents ได้เลย

Conclusion

Custom Agents ใน Amazon Q Developer CLI เป็น feature ที่ช่วยยกระดับการทำงานกับ Amazon Q Developer ให้มีการทำงานที่ตรงกับความต้องการของผู้ใช้อย่างมีนัยสำคัญ แทนที่จะต้องเผชิญกับ Context Overload, Context Confusion หรือ Scope Creep ผู้ใช้งานสามารถปรับแต่งให้ Amazon Q Developer ที่เข้าใจความต้องการของตัวเองได้มากยิ่งขึ้น

ด้วยการกำหนดบุคลิกภาพที่เฉพาะเจาะจง การเลือก tools ที่เหมาะสม การตั้งค่า permissions ที่เพิ่มความสะดวก การโหลด context อัตโนมัติ และการเชื่อมต่อ external services ผ่าน MCP ผู้ใช้งานสามารถเปลี่ยน Amazon Q Developer จากเครื่องมือที่ต้องคอยสอนทุกทั้งที่ start ขึ้นมาใหม่ ให้กลายเป็นเพื่อนร่วมงานที่เข้าใจความต้องการของเรา และ เข้าใจบริบทของงานได้มากขึ้น

การเริ่มต้นจากการสร้าง agent ที่เรียบง่ายสำหรับงานที่ทำบ่อย แล้วค่อยๆ เพิ่มความซับซ้อน จะช่วยให้ผู้ใช้งานค้นพบว่าการทำงานกับ Amazon Q Developer เป็นประสบการณ์ที่มีประสิทธิภาพ ราบรื่น และน่าสนใจมากขึ้น นี่คือจุดเริ่มต้นของยุคใหม่ที่ AI จะเป็นพาร์ทเนอร์ที่แท้จริงของทุกๆ คน