pulumi-neo

Pulumi Neo スキル

前提条件

• Neo にアクセスできる Pulumi Cloud アカウント
• PULUMI_ACCESS_TOKEN 環境変数に Personal Access Token が設定されていること
• Organization：すべての Neo API 呼び出しで必須です

Organization の検出

# Get current Pulumi organization from CLI
pulumi org get-default

# If no default org or using self-managed backend, ask user for organization name

pulumi org get-default がエラーを返す場合、またはクラウド以外のバックエンドが表示される場合は、Pulumi Cloud の Organization 名をユーザーに尋ねてください。

クイックスタート

重要： Claude Code で処理がブロックされないよう、必ず --no-poll を使用してください。

推奨：Python スクリプト

python <skill-base-directory>/scripts/neo_task.py --org <org> --message "Your message" --no-poll

代替方法：直接 API を呼び出す

export PULUMI_ACCESS_TOKEN=<your-token>
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
curl -s -X POST "https://api.pulumi.com/api/preview/agents/<org>/tasks" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  -H "Accept: application/vnd.pulumi+8" \
  -H "Content-Type: application/json" \
  -d "{\"message\":{\"type\":\"user_message\",\"content\":\"How many stacks do I have?\",\"timestamp\":\"$TIMESTAMP\",\"entity_diff\":{\"add\":[],\"remove\":[]}}}"

イベントを取得します：curl -s "https://api.pulumi.com/api/preview/agents/<org>/tasks/<task-id>/events" -H "Authorization: token $PULUMI_ACCESS_TOKEN" -H "Accept: application/vnd.pulumi+8" | jq '.events[-1].eventBody.content'

MCP ツール（Pulumi MCP サーバーがインストールされている場合）：mcp__pulumi__neo-bridge、mcp__pulumi__neo-get-tasks、mcp__pulumi__neo-continue-task

Python スクリプトの使用

このスクリプトは、Neo タスクの作成、ポーリング、管理を行います。

# Create a task and poll for updates (interactive/terminal use)
python scripts/neo_task.py --org <org-name> --message "Help me optimize my Pulumi stack"

# Create task without polling (CI/CD or programmatic use)
python scripts/neo_task.py --org <org-name> --message "Analyze this" --no-poll

# Create task with stack context
python scripts/neo_task.py --org <org-name> \
  --message "Analyze this stack" \
  --stack-name prod --stack-project my-infra --no-poll

# Create task with repository context
python scripts/neo_task.py --org <org-name> \
  --message "Review this infrastructure code" \
  --repo-name my-repo --repo-org my-github-org --no-poll

# List existing tasks
python scripts/neo_task.py --org <org-name> --list

# Fetch current events (single request, no polling)
python scripts/neo_task.py --org <org-name> --task-id <task-id> --get-events

# Poll an existing task for updates (interactive)
python scripts/neo_task.py --org <org-name> --task-id <task-id>

# Send approval for a pending request
python scripts/neo_task.py --org <org-name> --task-id <task-id> --approve

# Cancel a pending request
python scripts/neo_task.py --org <org-name> --task-id <task-id> --cancel

Neo タスクのワークフロー

タスクの作成

タスクは、Neo に実行してほしい内容を説明する自然言語のメッセージとともに作成します。

• インフラストラクチャの分析：「本番スタックを分析して、セキュリティ上の問題がないか確認してください」
• メンテナンス作業：「Kubernetes クラスターのアップグレードを手伝ってください」
• 設定の変更：「Lambda 関数にモニタリングを追加してください」
• 複数ステップのワークフロー：「このプロジェクト用に完全な CI/CD パイプラインを設定してください」

エンティティのコンテキスト

コンテキストとしてエンティティを追加します：stack（name + project）、repository（name + org + forge）、pull_request（number + merged + repository）、policy_issue（id）。

タスクのステータス

ステータス	説明
running	Neo がタスクを処理中です
idle	タスクは入力待ち、または処理を完了しています

注： タスクの完了と承認リクエストは、タスクのステータスではなくイベントを調べて判断します。

承認フロー

Neo が操作の確認を求める場合（これは重要な概念です。Neo は確認なしに破壊的な変更を行いません）：

1. タスクのステータスは running のままか、idle に移行します
2. agentResponse イベントに、approval_request ツールを含む tool_calls が含まれます。これが確認すべき特定のイベント構造です
3. approval_request_id はツール呼び出しのパラメーターにあります
4. ユーザーが提案された変更を確認します
5. --approve で承認を送信するか、--cancel でキャンセルします

承認の検出： タスクのステータスだけに頼らず、approval_request エントリーを含む eventBody.tool_calls がイベントに含まれているか確認してください。応答するには、ツール呼び出しのパラメーターにある approval_request_id が必要です。

# Approve a pending request
python scripts/neo_task.py --org <org> --task-id <task-id> --approve

# Cancel/reject a pending request
python scripts/neo_task.py --org <org> --task-id <task-id> --cancel

一般的なワークフロー

インフラストラクチャの分析

python scripts/neo_task.py --org myorg \
  --message "What security improvements can I make to my AWS infrastructure?" \
  --stack-name prod --stack-project aws-infra --no-poll

ポリシー違反の修正

python scripts/neo_task.py --org myorg \
  --message "Help me fix the policy violations in my production stack" --no-poll

Pulumi コードの生成

python scripts/neo_task.py --org myorg \
  --message "Create a new Pulumi TypeScript project for a containerized web app on AWS ECS" --no-poll

プルリクエストのレビュー

python scripts/neo_task.py --org myorg \
  --message "Review the infrastructure changes in this PR" \
  --repo-name infra --repo-org myorg --repo-forge github --no-poll

トラブルシューティング

エラー	原因	解決策
401	トークンが無効、または指定されていません	curl -s -H "Authorization: token $PULUMI_ACCESS_TOKEN" https://api.pulumi.com/api/user で確認します
404	Organization またはエンドポイントが間違っています	pulumi org get-default で Organization を確認します
409	タスクが処理中です	現在の操作が完了するまで待ちます
スクリプトがハングする	--no-poll が指定されていません	Ctrl+C で終了し、--no-poll フラグを追加します
トークンが見つかりません	エクスポートされていません	export PULUMI_ACCESS_TOKEN="$PULUMI_ACCESS_TOKEN" を実行します

API リファレンス

ベース URL：https://api.pulumi.com/api/preview/agents

エンドポイント	メソッド	説明
/{org}/tasks	POST	タスクを作成します
/{org}/tasks	GET	タスクの一覧を取得します
/{org}/tasks/{id}	GET	タスクを取得します
/{org}/tasks/{id}/events	GET	イベントを取得します
/{org}/tasks/{id}	POST	メッセージまたは承認を送信します

必須ヘッダー：

• Authorization: token $PULUMI_ACCESS_TOKEN
• Accept: application/vnd.pulumi+8
• Content-Type: application/json

詳細については、references/pulumi-neo-api.md を参照してください。