← ガイドトップに戻る

エージェントガイド

プロジェクト固有やタスク特化のAIアシスタントを作成・管理

概要

エージェントは特定の目的やプロジェクトに特化したAI設定です。ツール権限、リソース、動作をカスタマイズできます。

エージェント管理

基本コマンド

/agent                      # エージェント管理メニュー
/agent edit                 # 既存エージェントの編集

配置場所

ローカルエージェント（プロジェクト固有）

.amazonq/cli-agents/
├── dev-agent.json
├── aws-specialist.json
└── code-reviewer.json

グローバルエージェント（ユーザー全体）

~/.aws/amazonq/cli-agents/
├── general-assistant.json
├── documentation-writer.json
└── security-auditor.json

エージェント設定ファイル

基本構造

{
  "description": "エージェントの説明",
  "model": "claude-3-5-sonnet-20241022",
  "tools": ["fs_read", "fs_write", "execute_bash"],
  "allowedTools": ["fs_read"],
  "resources": [
    "file://README.md",
    "file://docs/**/*.md"
  ],
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["./src/**", "./docs/**"]
    },
    "execute_bash": {
      "allowedCommands": ["git status", "npm test"],
      "autoAllowReadonly": true
    }
  }
}

設定項目詳細

基本設定

リソース設定

ツール設定

実践的なエージェント例

1. 開発者エージェント

{
  "description": "フルスタック開発支援エージェント",
  "model": "claude-3-5-sonnet-20241022",
  "tools": ["fs_read", "fs_write", "execute_bash", "use_aws"],
  "allowedTools": ["fs_read"],
  "resources": [
    "file://README.md",
    "file://package.json",
    "file://src/**/*.ts",
    "file://docs/api.md"
  ],
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["./src/**", "./tests/**", "./docs/**"]
    },
    "execute_bash": {
      "allowedCommands": [
        "npm test",
        "npm run build",
        "git status",
        "git diff"
      ],
      "autoAllowReadonly": true
    },
    "use_aws": {
      "allowedServices": ["s3", "lambda", "dynamodb"],
      "autoAllowReadonly": true
    }
  }
}

2. ドキュメント作成エージェント

{
  "description": "技術文書作成専門エージェント",
  "model": "claude-3-5-sonnet-20241022",
  "tools": ["fs_read", "fs_write"],
  "allowedTools": ["fs_read", "fs_write"],
  "resources": [
    "file://README.md",
    "file://docs/**/*.md",
    "file://CHANGELOG.md"
  ],
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["./docs/**", "./README.md", "./*.md"]
    }
  }
}

3. セキュリティ監査エージェント

{
  "description": "セキュリティ監査・レビュー専門",
  "model": "claude-3-5-sonnet-20241022",
  "tools": ["fs_read", "execute_bash"],
  "allowedTools": ["fs_read"],
  "resources": [
    "file://security-policy.md",
    "file://src/**/*.py",
    "file://requirements.txt"
  ],
  "toolsSettings": {
    "execute_bash": {
      "allowedCommands": [
        "bandit -r src/",
        "safety check",
        "pip-audit"
      ],
      "autoAllowReadonly": true
    }
  }
}

4. AWS専門エージェント

{
  "description": "AWS インフラ管理専門エージェント",
  "model": "claude-3-5-sonnet-20241022",
  "tools": ["use_aws", "fs_read", "fs_write"],
  "allowedTools": ["use_aws"],
  "resources": [
    "file://infrastructure/**/*.yaml",
    "file://cloudformation/**/*.json"
  ],
  "toolsSettings": {
    "use_aws": {
      "allowedServices": ["ec2", "s3", "lambda", "cloudformation"],
      "autoAllowReadonly": true
    },
    "fs_write": {
      "allowedPaths": ["./infrastructure/**", "./scripts/**"]
    }
  }
}

エージェント作成手順

1. ローカルエージェント作成

# ディレクトリ作成
mkdir -p .amazonq/cli-agents

# エージェント設定ファイル作成
cat > .amazonq/cli-agents/my-project-agent.json << 'EOF'
{
  "description": "プロジェクト専用エージェント",
  "tools": ["fs_read", "fs_write", "execute_bash"],
  "resources": [
    "file://README.md",
    "file://src/**/*.js"
  ]
}
EOF

2. グローバルエージェント作成

# ディレクトリ作成（自動作成される場合もある）
mkdir -p ~/.aws/amazonq/cli-agents

# エージェント設定ファイル作成
cat > ~/.aws/amazonq/cli-agents/general-helper.json << 'EOF'
{
  "description": "汎用アシスタント",
  "tools": ["*"],
  "allowedTools": ["fs_read"]
}
EOF

エージェント優先順位

  1. ローカル優先: .amazonq/cli-agents/を最初に確認
  2. グローバル代替: ~/.aws/amazonq/cli-agents/を次に確認
  3. 名前衝突: ローカルエージェントが優先（警告表示）

ベストプラクティス

エージェント設計

  1. 目的特化: 特定のタスクや役割に特化
  2. 最小権限: 必要最小限のツール権限のみ付与
  3. リソース最適化: 関連ファイルのみ含める
  4. 命名規則: 分かりやすい名前とdescription

セキュリティ

  1. 権限制限: allowedPathsで書き込み範囲を制限
  2. コマンド制限: allowedCommandsで実行可能コマンドを限定
  3. 機密情報除外: 秘密鍵やパスワードファイルは除外
  4. 定期レビュー: エージェント設定の定期的な見直し

運用管理

  1. バージョン管理: エージェント設定をGitで管理
  2. チーム共有: プロジェクトエージェントをチームで共有
  3. ドキュメント化: エージェントの目的と使用方法を文書化
  4. テスト: エージェント設定の動作確認

トラブルシューティング

エージェントが見つからない

  1. パス確認: 正しいディレクトリにファイルがあるか確認
  2. ファイル名: .json拡張子が正しいか確認
  3. 権限確認: ファイルの読み取り権限確認

エージェントが動作しない

  1. JSON形式: 設定ファイルの構文エラー確認
  2. ツール権限: 必要なツールがtoolsに含まれているか確認
  3. パス設定: allowedPathsの設定が正しいか確認

権限エラー

  1. ツール設定: toolsSettingsの設定確認
  2. パス権限: ファイルシステムの権限確認
  3. コマンド権限: allowedCommandsの設定確認

関連機能