🤖 技術調査 - Scheduler-Driven Coding Agent Orchestration

# Claude Code
npm install -g @anthropic-ai/claude-code
claude login   # OAuth / API キー認証

# OpenAI Codex CLI
npm install -g @openai/codex
codex login    # OPENAI_API_KEY 設定

# 直接ダウンロード (推奨): https://github.com/equinix-labs/otel-cli/releases
#   例: otel-cli_0.4.6_darwin_arm64.tar.gz を展開して PATH に置く

# Homebrew (注意: 2026-05 時点で macOS の otel-cli formula が壊れており、
#  `--version` フラグすら無い古い版が入るケースを実測。動かない場合は releases バイナリを使う)
brew install otel-cli

-- 実装案
CREATE TABLE IF NOT EXISTS agent_runs (
    id            INTEGER PRIMARY KEY AUTOINCREMENT,
    agent_name    TEXT NOT NULL,
    skill_name    TEXT NOT NULL,
    started_at    DATETIME DEFAULT CURRENT_TIMESTAMP,
    finished_at   DATETIME,
    status        TEXT DEFAULT 'running',
    exit_code     INTEGER,
    error_message TEXT,
    total_tokens  INTEGER,
    total_cost_usd REAL
);

CREATE TABLE IF NOT EXISTS agent_outcomes (
    id            INTEGER PRIMARY KEY AUTOINCREMENT,
    run_id        INTEGER REFERENCES agent_runs(id),
    agent_name    TEXT,
    metric_name   TEXT,
    metric_value  REAL,
    metric_detail TEXT,
    recorded_at   DATETIME DEFAULT CURRENT_TIMESTAMP
);

#!/bin/bash
# 実装案
set -euo pipefail

AGENT_NAME="${1:?Usage: $0 <agent_name> <skill_name> [prompt]}"
SKILL_NAME="${2:?}"
PROMPT="${3:-/${SKILL_NAME}を実行して}"

export AGENT_LOOP_RUN_ID="${AGENT_LOOP_RUN_ID:-$(date +%Y%m%d_%H%M%S)_${AGENT_NAME}_${SKILL_NAME}}"
export OTEL_SERVICE_NAME="${OTEL_SERVICE_NAME:-scheduler-driven-agent}"
export OTEL_RESOURCE_ATTRIBUTES="agent.persona=${AGENT_NAME},agent.skill=${SKILL_NAME},deployment.environment=prod"
export CLAUDE_CODE_ENABLE_TELEMETRY=1

OUT="$(mktemp)"
trap 'rm -f "${OUT}"' EXIT

if command -v otel-cli &>/dev/null && [ -n "${OTEL_EXPORTER_OTLP_ENDPOINT:-}" ]; then
  otel-cli exec \
    --service "${OTEL_SERVICE_NAME}" \
    --name "invoke_agent ${SKILL_NAME}" \
    --kind internal \
    --attrs "gen_ai.operation.name=invoke_agent,gen_ai.agent.name=${SKILL_NAME},gen_ai.conversation.id=${AGENT_LOOP_RUN_ID}" \
    --fail \
    -- \
    claude -p --output-format json "${PROMPT}" > "${OUT}"
else
  claude -p --output-format json "${PROMPT}" > "${OUT}"
fi

EXIT_CODE=$?

if command -v sqlite3 &>/dev/null; then
  sqlite3 ~/agent_loop.db "INSERT INTO agent_runs (agent_name, skill_name, status, exit_code)
    VALUES ('${AGENT_NAME}', '${SKILL_NAME}',
    '$([ ${EXIT_CODE} -eq 0 ] && echo success || echo failure)', ${EXIT_CODE});" 2>/dev/null || true
fi

exit "${EXIT_CODE}"

<!-- 実装案 -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.example.agent.news-to-zenn</string>

  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/bash</string>
    <string>/Users/yourname/bin/run-agent.sh</string>
    <string>marketer</string>
    <string>news-to-zenn</string>
  </array>

  <!-- 毎日 06:30 (ローカル TZ。JST 環境なら JST 06:30 として実行される) -->
  <key>StartCalendarInterval</key>
  <dict>
    <key>Hour</key><integer>6</integer>
    <key>Minute</key><integer>30</integer>
  </dict>

  <key>EnvironmentVariables</key>
  <dict>
    <key>ANTHROPIC_API_KEY</key>
    <string>sk-ant-XXXXXXXX</string>
    <key>OTEL_EXPORTER_OTLP_ENDPOINT</key>
    <string>http://localhost:4317</string>
    <key>HOME</key>
    <string>/Users/yourname</string>
    <key>PATH</key>
    <string>/usr/local/bin:/usr/bin:/bin</string>
  </dict>

  <key>StandardOutPath</key><string>/tmp/com.example.agent.news-to-zenn.out</string>
  <key>StandardErrorPath</key><string>/tmp/com.example.agent.news-to-zenn.err</string>
  <key>KeepAlive</key><false/>
</dict>
</plist>

# ロード
launchctl load ~/Library/LaunchAgents/com.example.agent.news-to-zenn.plist

# 手動テスト
launchctl start com.example.agent.news-to-zenn

# アンロード (退役時は plist 削除も併用)
launchctl unload ~/Library/LaunchAgents/com.example.agent.news-to-zenn.plist

# Docker Compose で最小構成を起動する例
mkdir kestra && cd kestra
cat > docker-compose.yml <<'EOF'
services:
  kestra:
    image: kestra/kestra:v1.3-full   # 検証版。最新タグは https://hub.docker.com/r/kestra/kestra/tags で確認
    command: server standalone --worker-thread=128
    ports:
      - "8080:8080"
    environment:
      KESTRA_CONFIGURATION: |
        datasources:
          postgres:
            url: jdbc:postgresql://postgres:5432/kestra
            username: kestra
            password: kestra
        kestra:
          server:
            workerTaskRestartStrategy: NEVER  # 二重起動防止
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: kestra
      POSTGRES_PASSWORD: kestra
      POSTGRES_DB: kestra
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kestra"]
      interval: 10s
EOF

docker compose up -d

# 実装案
id: agent_news_to_zenn
namespace: daily.morning

triggers:
  - id: daily_schedule
    type: io.kestra.plugin.core.trigger.Schedule
    cron: "30 21 * * *"   # UTC 21:30 = JST 06:30
    timezone: UTC
    recoverMissedSchedules: LAST

tasks:
  - id: invoke_skill
    type: io.kestra.plugin.scripts.shell.Commands
    timeout: PT3H
    env:
      OTEL_SERVICE_NAME: "scheduler-driven-agent"
      OTEL_RESOURCE_ATTRIBUTES: "agent.persona=marketer,agent.skill=news-to-zenn,deployment.environment=prod"
      OTEL_EXPORTER_OTLP_ENDPOINT: "http://localhost:4317"
      OTEL_TRACES_EXPORTER: "otlp"
      OTEL_METRICS_EXPORTER: "otlp"
      OTEL_LOGS_EXPORTER: "otlp"
      CLAUDE_CODE_ENABLE_TELEMETRY: "1"
      CLAUDE_CODE_ENHANCED_TELEMETRY_BETA: "1"
      KESTRA_EXECUTION_ID: "{{ execution.id }}"
      AGENT_LOOP_RUN_ID: "{{ execution.id }}"
    commands:
      - |
        set +e
        otel-cli exec \
          --service "${OTEL_SERVICE_NAME}" \
          --name 'invoke_agent news-to-zenn' \
          --kind internal \
          --attrs 'gen_ai.operation.name=invoke_agent,gen_ai.agent.name=news-to-zenn' \
          --fail \
          -- \
          /path/to/agent-loop/scripts/run-skill.sh \
            marketer news-to-zenn
        EXIT=$?
        echo "EXIT=${EXIT}"
        exit "${EXIT}"

  - id: notify
    type: io.kestra.plugin.scripts.shell.Commands
    allowFailure: true
    commands:
      - echo "[notify] status={{ execution.state.current }} run={{ execution.id }}"

errors:
  - id: on_failure
    type: io.kestra.plugin.scripts.shell.Commands
    allowFailure: true
    commands:
      - echo "[error] Flow failed: {{ execution.id }}"

# ~/.codex/config.toml
# 実装案: developers.openai.com/codex/config-advanced の [otel] を参考
[otel]
environment = "prod"
exporter = { otlp-grpc = { endpoint = "http://localhost:4317" } }
trace_exporter = { otlp-grpc = { endpoint = "http://localhost:4317" } }
metrics_exporter = { otlp-grpc = { endpoint = "http://localhost:4317" } }
# PII opt-in: 必ず false から始める
log_user_prompt = false

# .github/workflows/agent-daily.yml
# 実装案: docs.github.com/actions の schedule イベントを参考
name: Daily Coding Agent

on:
  schedule:
    - cron: "30 21 * * *"   # UTC 21:30 = JST 06:30
  workflow_dispatch:
    inputs:
      skill_name:
        description: "実行するスキル名"
        required: false
        default: "news-to-zenn"

permissions:
  contents: write

env:
  SKILL_NAME: ${{ inputs.skill_name || 'news-to-zenn' }}
  AGENT_NAME: marketer
  OTEL_SERVICE_NAME: scheduler-driven-agent

jobs:
  run-agent:
    runs-on: ubuntu-latest
    timeout-minutes: 180
    steps:
      - uses: actions/checkout@v4

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Set run ID
        id: run_id
        run: echo "run_id=${GITHUB_RUN_ID}_${GITHUB_RUN_ATTEMPT}_${AGENT_NAME}_${SKILL_NAME}" >> "$GITHUB_OUTPUT"

      - name: Run coding agent
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          AGENT_LOOP_RUN_ID: ${{ steps.run_id.outputs.run_id }}
          OTEL_RESOURCE_ATTRIBUTES: "agent.persona=${{ env.AGENT_NAME }},agent.skill=${{ env.SKILL_NAME }},deployment.environment=prod,ci.run_id=${{ github.run_id }}"
          CLAUDE_CODE_ENABLE_TELEMETRY: "1"
          CLAUDE_CODE_ENHANCED_TELEMETRY_BETA: "1"
          OTEL_TRACES_EXPORTER: "otlp"
          OTEL_METRICS_EXPORTER: "otlp"
          OTEL_EXPORTER_OTLP_ENDPOINT: ${{ secrets.OTEL_COLLECTOR_ENDPOINT || '' }}
        run: |
          set -euo pipefail
          PROMPT="/${{ env.SKILL_NAME }}を実行して"
          claude -p --output-format json --dangerously-skip-permissions "${PROMPT}" > result.json

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: result-${{ github.run_id }}
          path: result.json
          retention-days: 30

launchctl start com.example.agent.news-to-zenn
tail -f /tmp/com.example.agent.news-to-zenn.out

curl -s -u admin@example.com:kestra1234 \
  -X POST \
  "http://localhost:8080/api/v1/main/executions/daily.morning/agent_news_to_zenn" \
  -H "Content-Type: multipart/form-data"

open http://localhost:8080/ui/

gh workflow run agent-daily.yml -f skill_name=news-to-zenn
gh run list --workflow=agent-daily.yml
gh run view <run-id> --log

launchctl kickstart -k gui/$(id -u)/com.example.agent.news-to-zenn

# Replay (UI または API)
curl -s -u admin@example.com:kestra1234 \
  -X POST \
  "http://localhost:8080/api/v1/main/executions/<execution-id>/replay"

gh run rerun <run-id>
gh run rerun <run-id> --failed

sqlite3 ~/agent_loop.db <<'SQL'
SELECT
    skill_name,
    COUNT(*) AS total_runs,
    SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) AS success,
    SUM(CASE WHEN status = 'failure' THEN 1 ELSE 0 END) AS failure,
    ROUND(AVG(total_cost_usd), 4) AS avg_cost_usd
FROM agent_runs
WHERE started_at >= datetime('now', '-7 days')
GROUP BY skill_name
ORDER BY total_runs DESC;
SQL

# 一時停止
launchctl unload ~/Library/LaunchAgents/com.agentloop.kestra.plist

# 完全退役 (unload + rm)
launchctl unload ~/Library/LaunchAgents/com.example.foo.plist
rm ~/Library/LaunchAgents/com.example.foo.plist

# 起動
launchctl load ~/Library/LaunchAgents/com.agentloop.kestra.plist

# 状態確認
launchctl list | grep com.agentloop

# Kestra 本体の再起動
launchctl unload ~/Library/LaunchAgents/com.agentloop.kestra.plist
launchctl load  ~/Library/LaunchAgents/com.agentloop.kestra.plist

# Flow の更新デプロイ
./deploy/deploy-flows.sh news

# 特定 Flow の無効化
curl -s -u admin@example.com:kestra1234 -X POST \
  "http://localhost:8080/api/v1/main/flows/<namespace>/<flow_id>/disable"

gh workflow disable <workflow_name_or_id>
gh workflow enable <workflow_name_or_id>
gh workflow run <workflow_name> --ref <branch>

# 最新 executions
curl -s -u admin@example.com:kestra1234 \
  "http://localhost:8080/api/v1/main/executions?namespace=news&pageSize=10"

# 特定 execution 詳細
curl -s -u admin@example.com:kestra1234 \
  "http://localhost:8080/api/v1/main/executions/<execution_id>"

-- 直近 24h の実行状況
SELECT run_id, agent_name, skill_name, status, started_at, finished_at,
       ROUND(EXTRACT(EPOCH FROM (finished_at - started_at))/60, 1) AS duration_min
FROM   agent_runs
WHERE  started_at > NOW() - INTERVAL '24 hours'
ORDER  BY started_at DESC;

-- skill 別 outcome サマリ (3-state)
SELECT skill_name, status, COUNT(*) AS cnt
FROM   agent_runs
WHERE  started_at > NOW() - INTERVAL '7 days'
GROUP  BY skill_name, status
ORDER  BY skill_name, status;

# Kestra ログを run_id でフィルタ
curl -s -u admin@example.com:kestra1234 \
  "http://localhost:8080/api/v1/main/logs?namespace=news&flowId=to_zenn&pageSize=100" \
  | jq '.results[] | select(.message | contains("run_id=<RUN_ID>"))'

# Jaeger backend で gen_ai.conversation.id=<RUN_ID> で検索
# → invoke_agent span 以下に claude_code.interaction, llm_request, tool が nest

triggers:
  - id: daily
    type: io.kestra.plugin.core.trigger.Schedule
    cron: "0 7 * * *"          # 07:00 JST に変更
    timezone: Asia/Tokyo
    recoverMissedSchedules: LAST

on:
  schedule:
    - cron: "0 22 * * *"   # UTC 22:00 = JST 07:00。TZ は UTC 固定

- id: fan_out
  type: io.kestra.plugin.core.flow.ForEach
  values: "{{ outputs.extract_picks.vars.picks }}"
  concurrencyLimit: 3
  tasks:
    - id: worker
      type: io.kestra.plugin.core.flow.Subflow
      namespace: news
      flowId: to_zenn
      inputs:
        pick_id: "{{ taskrun.value }}"
      wait: true

strategy:
  matrix:
    skill: [news-to-zenn, dr-to-zenn, tech-dr-to-zenn]
  max-parallel: 2

# 1. 現在のバージョンを記録
claude --version
codex --version

# 2. staging でアップデート
npm update -g @anthropic-ai/claude-code
npm update -g @openai/codex

# 3. console exporter で疎通確認してから otlp に切替
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claude -p "echo test" --output-format json

# 4. silent no-op (Issue #50567) を踏んでいないことを確認できたら otlp へ
export OTEL_METRICS_EXPORTER=otlp

# 5. CHANGELOG で span 名・属性変更を確認
# 6. Grafana ダッシュボードの metric 名ハードコードを点検

# dispatcher の pseudo-code
EXISTING=$(psql $DB -qtA -c "SELECT status FROM agent_runs WHERE skill_name='$SKILL' AND started_at > NOW()-INTERVAL'1 day' ORDER BY started_at DESC LIMIT 1")
case "$EXISTING" in
  success)   echo "already_done: skip"; exit 0 ;;
  partial)   exec run-skill.sh $AGENT $SKILL "$PROMPT --resume" ;;
  *)         exec run-skill.sh $AGENT $SKILL "$PROMPT" ;;
esac

kestra:
  server:
    workerTaskRestartStrategy: NEVER
    liveness:
      timeout: 5m
      initialDelay: 5m

-- stale running を検出して failure に強制更新
UPDATE agent_runs
SET    status = 'failure',
       finished_at = NOW(),
       error_message = 'reaper: exceeded 12h timeout'
WHERE  status = 'running'
  AND  started_at < NOW() - INTERVAL '12 hours';

if [ -f "${HOME}/.zshrc" ]; then
  set -a
  eval "$(grep -E '^export (GITHUB_TOKEN_|NPM_TOKEN|APIKEY_|BUFFER_API_TOKEN|PAT_)' "${HOME}/.zshrc")"
  set +a
fi

processors:
  attributes/pii_scrub:
    actions:
      - key: codex.tool_result.output
        action: hash
      - key: gen_ai.input.messages
        action: delete
      - key: gen_ai.output.messages
        action: delete

invoke_workflow {dispatch.name}    kind=INTERNAL  service=agent-loop   ← Kestra task span
  └── invoke_agent {skill}         kind=INTERNAL  service=agent-loop   ← otel-cli exec が発行
        └── claude_code.interaction  kind=INTERNAL  service=claude-code  ← claude -p が発行
              ├── claude_code.llm_request   (API 呼び出し)
              └── claude_code.tool          (ツール実行)

case "${OVERALL_STATUS}" in
  partial_failed) exit 1 ;;
  failed)         exit 2 ;;
  *)              exit 0 ;;
esac

dispatcher Flow:
  1. 処理対象を取得・絞り込み
  2. 3-state 判定 (already_done / partial_retry / fresh)
  3. ForEach で worker Subflow を並列起動
  4. finally: 完了通知

worker Flow:
  1. run-skill.sh 経由で claude -p を起動
  2. EXIT trap で全差分 commit & push
  3. 結果 DB に書き込む
  4. 3-state exit code で終了

# start span (自前で span_id を生成し --force-span-id で固定する)
START_SPAN_ID=$(openssl rand -hex 8)
otel-cli span \
  --name "invoke_agent_start $SKILL" \
  --kind internal \
  --attrs "gen_ai.operation.name=invoke_agent,gen_ai.conversation.id=$RUN_ID" \
  --force-span-id "$START_SPAN_ID"

# (agent 実行...)

# complete span (SpanLink で start span を参照)
otel-cli span \
  --name "invoke_agent_complete $SKILL" \
  --kind internal \
  --attrs "gen_ai.conversation.id=$RUN_ID,span_link.span_id=$START_SPAN_ID"

# 注: otel-cli の `--tp-print` で `traceparent` を取得して span_id 部分を抽出する方法もあります