Comprehensive toolkit for agentapi-proxy: API client for session management and webhook automation. Includes API authentication, session lifecycle management, and webhook configuration for GitHub and custom services.

version
2.3.0

Install

/plugin install ccplant@takutakahashi-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add takutakahashi/marketplace.

Contents

Discovered from source

Skills 7

agentapi-proxy API

This skill provides guidance for interacting with the agentapi-proxy API.

CLI: agentapi-proxy client

agentapi-proxy client を使うことで全リソースへアクセスできます。以下のサブコマンドが利用可能です:

サブコマンド用途操作
taskタスク管理create / list / get / update / delete
memoryメモリ管理create / list / get / update / delete / upsert
assetHTML asset アップロードcreate
scheduleスケジュール管理create / list / get / apply / delete
webhookWebhook 管理create / list / get / apply / delete / regenerate-secret
slackbotSlackBot 管理create / list / get / apply / delete
sendエージェントへのメッセージ送信-
statusエージェントのステータス取得-
eventsエージェントイベントの監視-
history会話履歴の取得-
delete-session現在のセッションの削除-
send-notificationプッシュ通知の送信-
summarize-draftsドラフトメモリの要約-

Note: タスクグループ (task-group)、セッションプロファイル、サンドボックスポリシー、 リソース移管は CLI 未対応です。MCP ツールまたは REST API を使用してください。

接続設定

エンドポイントと認証は以下の環境変数から自動解決されます:

export AGENTAPI_PROXY_SERVICE_HOST=<host>
export AGENTAPI_PROXY_SERVICE_PORT_HTTP=<port>  # または AGENTAPI_PROXY_SERVICE_PORT
export AGENTAPI_KEY=<api-key>                    # 省略可(認証不要な場合)

または --endpoint フラグで明示的に指定:

agentapi-proxy client <command> --endpoint http://proxy:8080 --session-id SESSION_ID

Core Workflows

Managing Tasks

Tasks are units of work associated with a session. There are two types: agent tasks (created by the AI agent) and user tasks (created for human action).

Create a task:

# Agent task (default) - work performed by the agent
agentapi-proxy client task create \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID \
  --title "Implement feature X" \
  --task-type agent \
  --scope user

# User task - action required from a human
agentapi-proxy client task create \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID \
  --title "Review PR #123" \
  --task-type user \
  --scope user \
  --description "Please review and approve the pull request" \
  --link "https://github.com/owner/repo/pull/123|PR #123"

List tasks:

# List all tasks
agentapi-proxy client task list \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID

# Filter by status (todo / done)
agentapi-proxy client task list \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID \
  --status todo

# Filter by type
agentapi-proxy client task list \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID \
  --task-type user

Update a task:

agentapi-proxy client task update TASK_ID \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID \
  --status done

Get / Delete a task:

# Get
agentapi-proxy client task get TASK_ID \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID

# Delete
agentapi-proxy client task delete TASK_ID \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID

See TASK_REFERENCE.md for complete task API documentation.

Managing Memory Entries

Memory entries allow storing and retrieving contextual information for agents and users. Supports user-scoped (private) and team-scoped (shared) memories.

Create a memory entry:

# User-scoped memory
agentapi-proxy client memory create \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID \
  --title "Project conventions" \
  --content "Always use TypeScript for new files. Follow ESLint rules." \
  --scope user

# Team-scoped memory with tags
agentapi-proxy client memory create \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID \
  --title "Team knowledge" \
  --content-file /tmp/notes.md \
  --scope team --team-id myorg/myteam \
  --tag project=myapp

List memory entries:

# List all user memories
agentapi-proxy client memory list \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID \
  --scope user

# List team memories filtered by tag
agentapi-proxy client memory list \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID \
  --scope team --team-id myorg/myteam \
  --tag project=myapp

# Output in Markdown format (suitable for injection into CLAUDE.md)
agentapi-proxy client memory list \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID \
  --format markdown

Get / Update / Delete a memory entry:

# Get
agentapi-proxy client memory get MEMORY_ID \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID

# Update
agentapi-proxy client memory update MEMORY_ID \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID \
  --title "Updated conventions" \
  --content "Updated content"

# Delete
agentapi-proxy client memory delete MEMORY_ID \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID

Upsert (create or update by key tags):

# Create or update a memory identified by key tags
agentapi-proxy client memory upsert \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID \
  --title "Session summary" \
  --content-file /tmp/content.md \
  --key project=myapp --key env=prod \
  --scope user

upsert はキータグで既存のメモリを検索し、見つかれば更新、なければ作成します。定期的なメモリ更新に便利です。

Summarize draft memories:

# セッション終了後、ドラフトメモリを要約して本メモリに統合
agentapi-proxy client summarize-drafts \
  --endpoint http://proxy:8080 \
  --session-id SESSION_ID \
  --source-session-id SOURCE_SESSION_ID \
  --scope user \
  --key project=myapp

Uploading HTML Assets

Use agentapi-proxy client asset create to upload HTML and receive an externally reachable URL. The server stores the HTML in the configured asset backend, usually nginx-backed storage by default or S3 when configured.

Upload from a file:

agentapi-proxy client asset create \
  --endpoint http://proxy:8080 \
  --html-file ./index.html

Upload from stdin:

cat ./index.html | agentapi-proxy client asset create \
  --endpoint http://proxy:8080 \
  --html-file -

Return JSON instead of only the URL:

agentapi-proxy client asset create \
  --endpoint http://proxy:8080 \
  --html-file ./index.html \
  --format json

The response URL can be fetched without API authentication if the deployment exposes the /assets route through ingress to the asset service.

Managing Task Groups

Task groups provide a way to organize and manage related tasks together.

Note: タスクグループは CLI 未対応です。MCP ツールを使用してください。

# Create a task group
Use the mcp__ccplant__create_task_group tool

# List task groups
Use the mcp__ccplant__list_task_groups tool

# Delete a task group
Use the mcp__ccplant__delete_task_group tool

Transferring Resource Ownership

POST /resources/transfer transfers a supported resource between user and team ownership scopes. The supported resource_type values are memory, task, task_group, webhook, slackbot, session_profile, and sandbox_policy. Use dry_run: true to validate access and the destination without changing ownership.

Note: Resource transfer is not yet available via agentapi-proxy client. Use the REST API directly.

curl -X POST https://api.example.com/resources/transfer \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "session_profile",
    "resource_id": "profile-abc123",
    "target_scope": "team",
    "target_team_id": "myorg/backend",
    "dry_run": true
  }'

Managing External Session Managers

External Session Manager registration, listing, update, deletion, token rotation, and heartbeat are available through /external-session-managers. They are not yet available via an agentapi-proxy client subcommand, so use the REST API directly. See ../../references/API_REFERENCE.md and the session-manager-setup skill for request fields, native installation, allocator labels, and lifecycle commands.

Managing Files

Files (e.g., SSH keys, configuration files) can be registered and will be placed inside agent sessions at startup. Files are stored securely and automatically mounted in agent containers.

Note: File management is not yet available via CLI. Use the API directly:

# Create a file (e.g., SSH private key)
curl -X POST https://api.example.com/files \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SSH Private Key",
    "path": "/home/agentapi/.ssh/id_rsa",
    "content": "-----BEGIN OPENSSH PRIVATE KEY-----\n...",
    "permissions": "0600"
  }'

# List all files
curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.example.com/files

# Get a specific file (including content)
curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.example.com/files/FILE_ID

# Update a file
curl -X PUT https://api.example.com/files/FILE_ID \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated SSH Key",
    "content": "-----BEGIN OPENSSH PRIVATE KEY-----\n..."
  }'

# Delete a file
curl -X DELETE https://api.example.com/files/FILE_ID \
  -H "X-API-Key: YOUR_API_KEY"

Files are automatically mounted at the specified path in agent sessions. The provisioner writes files with mode 0600 by default for security.

Managing Credentials

Credentials (e.g., Claude Code OAuth tokens) can be uploaded and managed via the API. These credentials are securely stored and automatically mounted in agent sessions.

Note: Credentials management is not yet available via CLI. Use the API directly:

# Upload credentials (e.g., auth.json)
curl -X PUT https://api.example.com/credentials/auth \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "claudeAiOauth": {
      "accessToken": "sk-ant-...",
      "refreshToken": "...",
      "expiresAt": 1234567890
    }
  }'

# Get credential metadata
curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.example.com/credentials/auth

# Delete credentials
curl -X DELETE https://api.example.com/credentials/auth \
  -H "X-API-Key: YOUR_API_KEY"

Credentials are automatically mounted at /credentials/{name}.json in agent sessions.

Managing Settings

Settings include Bedrock configuration, MCP servers, plugin marketplaces, and custom environment variables. Settings can be configured at user or team level.

Note: Settings management is not yet available via CLI. Use the API directly:

# Get settings
curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.example.com/settings/alice

# Update settings (e.g., configure Bedrock)
curl -X PUT https://api.example.com/settings/alice \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bedrock": {
      "enabled": true,
      "model": "anthropic.claude-3-sonnet-20240229-v1:0"
    },
    "mcp_servers": {
      "github": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_TOKEN": "ghp_xxxx"
        }
      }
    },
    "enabled_plugins": ["commit@claude-plugins-official"]
  }'

See API_REFERENCE.md and API_REFERENCE.md for complete details.

API Reference

For complete API endpoint documentation, permissions, and authentication details, see:

CCPlant Session

Delegate only concrete, independently executable work. Keep ownership of planning, dependency ordering, result review, and final integration in the parent session.

Configure access

Resolve the proxy URL from the explicit variable first, then the Kubernetes service variables:

CCPLANT_URL="${AGENTAPI_PROXY_URL:-http://${AGENTAPI_PROXY_SERVICE_HOST}:${AGENTAPI_PROXY_SERVICE_PORT_HTTP:-${AGENTAPI_PROXY_SERVICE_PORT:-8080}}}"

Use AGENTAPI_KEY for authentication. Never print the key or place secrets in task messages. Stop and ask the user for configuration if the URL or required authentication cannot be resolved.

Plan delegation

Before creating sessions:

  1. Split work into bounded tasks with minimal overlap.
  2. State the expected artifact, relevant paths, constraints, and completion checks for each task.
  3. Identify dependencies. Start dependent work only after its prerequisite result is available.
  4. Assign a distinct branch or non-overlapping file ownership when sessions will edit the same repository.
  5. Keep the number of sessions proportional to truly parallel work; do not create a session for trivial work.

Create a session

Build JSON with jq so multiline instructions are escaped safely. Prefer the configured agent type, falling back to codex-acp:

TASK='Inspect the authentication package. Report the root cause with file and line references. Do not modify files.'
PAYLOAD="$(jq -n \
  --arg message "$TASK" \
  --arg agent_type "${AGENTAPI_AGENT_TYPE:-codex-acp}" \
  --arg repository "${AGENTAPI_REPO_FULLNAME:-unknown}" \
  '{
    tags: {purpose: "parallel-work", repository: $repository},
    params: {
      message: $message,
      agent_type: $agent_type,
      oneshot: false,
      session_ttl: "24h"
    }
  }')"

RESPONSE="$(curl --fail-with-body --silent --show-error \
  -X POST "$CCPLANT_URL/start" \
  -H "X-API-Key: $AGENTAPI_KEY" \
  -H 'Content-Type: application/json' \
  --data "$PAYLOAD")"
SESSION_ID="$(jq -er '.session_id' <<<"$RESPONSE")"

Create multiple independent sessions without waiting for one to finish before starting the next. Record each session ID together with its assignment. Do not use oneshot: true when follow-up questions may be necessary.

Include repository and branch context in the task message when edits are requested. Explicitly require the session to preserve unrelated changes, run relevant checks, and return commit or PR details if that is the intended handoff.

Communicate and inspect

Use the CLI for normal interaction:

agentapi-proxy client status \
  --endpoint "$CCPLANT_URL" --session-id "$SESSION_ID"

agentapi-proxy client history \
  --endpoint "$CCPLANT_URL" --session-id "$SESSION_ID"

agentapi-proxy client send 'Please also run the focused integration test and report its output.' \
  --endpoint "$CCPLANT_URL" --session-id "$SESSION_ID"

Use events for short interactive observation. For automation, prefer bounded long-polling so the parent remains responsive:

curl --fail-with-body --silent --show-error \
  -H "X-API-Key: $AGENTAPI_KEY" \
  "$CCPLANT_URL/sessions/$SESSION_ID/messages/wait?timeout=30"

After an update, call history to read the actual messages. Reuse the returned timestamp as the URL-encoded since value on the next wait when appropriate. Treat a timeout ({"updated":false}) as normal, not as failure.

Review and integrate

For every delegated task:

  1. Read the final history; do not infer success from status alone.
  2. Verify claimed files, commits, PRs, and test results in the authoritative repository.
  3. Send a focused follow-up if evidence is missing or the output does not meet the assignment.
  4. Resolve conflicting recommendations in the parent session.
  5. Integrate results in dependency order and run the combined verification.
  6. Report which session produced each accepted result and disclose incomplete or failed tasks.

Do not delete sessions merely because their task finished. Delete one only when the user requested cleanup or retention policy requires it:

curl --fail-with-body --silent --show-error \
  -X DELETE -H "X-API-Key: $AGENTAPI_KEY" \
  "$CCPLANT_URL/sessions/$SESSION_ID"

Handle failures

  • On 401 or 403, verify endpoint, key, scope, and session ownership without exposing credentials.
  • On 404, confirm the recorded session ID and whether TTL or oneshot cleanup removed it.
  • On 502, retry status after a short interval; provisioning may still be in progress.
  • If a session stalls, inspect history before sending a concise unblock message.
  • If repeated attempts make no progress, stop creating replacements and report the blocker.

cycle — 繰り返し実行スキル

このスキルは agentapi-proxy client cycle コマンドを使い、エージェントセッションを条件が満たされるまで自動的に繰り返し実行する方法を提供します。

概要

cycle コマンドは、Claude Code の Stop hook に組み込まれ、エージェントが停止するたびに自動的にメッセージを再送信します。

基本抽象

  • /tmp/check/CYCLE_ENABLED ファイルが存在するとキック、そのファイル内容がメッセージとして送信されます
  • ファイルが存在しない場合、cycle は何もしない(ノーオペレーション)
  • ループを終了するには CYCLE_ENABLED を削除する(エージェント自身も実行できる)
  • Stop hook は永続的に登録され、CYCLE_ENABLED の有無によって動作を制御

自動付加される完了確認指示

cycle が送信するメッセージには、以下の指示が 自動的に追記 されます。エージェントは達成条件を確認し、満たしていれば CYCLE_ENABLED を削除してループを自律的に終了します:

---
⚠️ [cycle セッション] このメッセージを受け取ったら、まず上記の達成条件を確認してください。
条件をすべて満たしている場合は、追加の作業は行わずに直ちに以下のコマンドを実行してサイクルを終了させてください:

```bash
rm -f /tmp/check/CYCLE_ENABLED

条件を満たしていない場合は、引き続き作業を行ってください。


---

## 基本的な使い方

### コマンド構文

```bash
agentapi-proxy client cycle [flags]

重要: メッセージは CLI 引数ではなく、/tmp/check/CYCLE_ENABLED のファイル内容から読み取ります。

フラグ一覧

フラグ説明デフォルト
--max-count N最大サイクル回数(0 = 無制限)10
--session-idセッション ID(環境変数 AGENTAPI_SESSION_ID でも指定可)-
--endpointプロキシのエンドポイント URL環境変数から自動解決

手動でエーブル化する例

# CYCLE_ENABLED にメッセージを書き込んでキック開始
mkdir -p /tmp/check
echo "タスクを続けてください" > /tmp/check/CYCLE_ENABLED

# ループを止めたいときは削除する
rm -f /tmp/check/CYCLE_ENABLED

# 最大 5 回まで制限
agentapi-proxy client cycle --max-count 5

# セッション ID とエンドポイントを明示指定
agentapi-proxy client cycle \
  --session-id my-session \
  --endpoint http://localhost:8080

セッション作成時に cycle を設定する方法

セッションを作成する際に cycle_message パラメータを指定すると、以下が自動実行されます:

  1. /tmp/check/CYCLE_ENABLED に cycle_message の内容が書き込まれる(セッション起動時に作成)
  2. Stop hook に agentapi-proxy client cycle が登録される(メッセージ引数なし)
  3. エージェントが停止するたびに hook が発火→ CYCLE_ENABLED を読んで送信

API パラメータ

パラメータ型説明
cycle_messagestring/tmp/check/CYCLE_ENABLED に書き込まれるメッセージ。空の場合は cycle 無効
cycle_max_countint最大繰り返し回数(0 = 無制限)。デフォルト 10。cycle_message が必要

セッション作成例(API)

{
  "params": {
    "message": "テストが全て通るまでコードを修正してください",
    "cycle_message": "続きの作業を進めてください",
    "cycle_max_count": 10
  }
}

動作フロー

1. セッション開始(cycle_message 付き)
   ↓
2. agentapi-proxy が /tmp/check/CYCLE_ENABLED にメッセージを書き込む
   agentapi-proxy が Stop hook (引数なし) を Claude Code 設定に注入
   ↓
3. Claude Code がタスクを処理して停止
   ↓
4. Stop hook が非同期で実行:
   nohup agentapi-proxy client cycle [--max-count N] >> /tmp/cycle.log 2>&1 &
   ↓
5. cycle コマンドが以下を順番に実行:
   a. /tmp/check/CYCLE_ENABLED が存在しない → "CYCLE_ENABLED not found" と出力して即時終了
   b. CYCLE_ENABLED の内容をメッセージとして読み込む
   c. /tmp/check/CYCLE_COUNT が max-count に達した → CYCLE_ENABLED を削除して即時終了
   d. セッションが stable 状態になるまで最大 120 秒待機(2 秒間隔でポーリング)
   e. メッセージ + cycleConditionCheckSuffix を自動付加して送信
   ↓
6. エージェントが作業を継続
   ・達成条件を満たした → rm -f /tmp/check/CYCLE_ENABLED してループ終了
   ・まだ未達成 → 作業を続けて再度停止 → ステップ 3 へ

ループの制御

ループを有効化する(エーブル)

mkdir -p /tmp/check
echo "続きの作業を進めてください" > /tmp/check/CYCLE_ENABLED

ループを無効化する(ディスエーブル)

rm -f /tmp/check/CYCLE_ENABLED

エージェントが自律的にループを終了する(自律的完了)

エージェントは cycleConditionCheckSuffix の指示に従い、達成条件を満たしたら以下を実行します:

rm -f /tmp/check/CYCLE_ENABLED

管理ファイル

ファイルパス用途
/tmp/check/CYCLE_ENABLED存在すると cycle が有効。内容が送信メッセージ
/tmp/check/CYCLE_COUNT現在の繰り返し回数を記録するカウンター
/tmp/cycle.logcycle コマンドの実行ログ

カウンターの動作

  • カウンターはメッセージ送信前にインクリメントされます
  • /tmp/check/CYCLE_COUNT が存在しない場合は 0 として扱います
  • --max-count が 0 の場合、カウンターチェックはスキップされます
  • 上限に達した場合、CYCLE_ENABLED が自動的に削除されます

ユースケース

1. テストが通るまで修正を繰り返す

{
  "params": {
    "message": "make test を実行してテストが全て通るまでコードを修正してください。全テストが通ったらループを終了してください。",
    "cycle_message": "テストの修正を続けてください",
    "cycle_max_count": 20
  }
}

2. lint/test が通るまで CI を改善する

{
  "params": {
    "message": "lint と test を実行して全て通るまで修正してください。完了したらループを終了してください。",
    "cycle_message": "引き続き lint/test を修正してください",
    "cycle_max_count": 15
  }
}

3. 無制限にタスクを処理し続ける

{
  "params": {
    "message": "Issue リストのタスクを順番に処理してください",
    "cycle_message": "次のタスクを処理してください",
    "cycle_max_count": 0
  }
}

4. 手動で CYCLE_ENABLED を使ってループを制御する

# cycle をエーブル化(メッセージも書き込む)
mkdir -p /tmp/check
echo "作業を続けてください" > /tmp/check/CYCLE_ENABLED

# cycle を無効化(いつでも実行可能)
rm -f /tmp/check/CYCLE_ENABLED

注意事項

  • cycle_message が空の場合、Stop hook は注入されません(cycle 無効)
  • cycle_max_count のデフォルトは 10(0 の場合のみ無制限)
  • --max-count の上限に達したとき、CYCLE_ENABLED が自動的に削除されます
  • cycle コマンドは Stop hook から nohup で非同期実行されるため、hook の完了をブロックしません
  • セッションが stable 状態になるまで最大 120 秒 待機します(2 秒間隔でポーリング)
  • カウンターはメッセージ送信前にインクリメントされます
  • Stop hook にメッセージ引数は無い(CYCLE_ENABLED の内容を直接読む)

Schedule Management

This skill provides guidance for managing agentapi-proxy schedules that automatically create sessions at specified times or intervals.

Overview

Schedules enable automatic session creation at specific times or on recurring intervals. Each schedule has:

  • Name: Descriptive name for the schedule
  • Execution Type: One-time (scheduled_at) or recurring (cron_expr)
  • Session Config: Environment variables, tags, and initial messages for created sessions
  • Status: Active, paused, or completed
  • Scope: User-level or team-level access

Core Workflows

Creating a Schedule

One-Time Delayed Execution

First, create a JSON file with your schedule configuration:

cat > schedule.json <<'EOF'
{
  "name": "Code Review Session",
  "scheduled_at": "2025-01-15T14:00:00Z",
  "session_config": {
    "tags": {
      "repository": "org/repo",
      "task": "code-review"
    },
    "params": {
      "message": "Review all open PRs"
    }
  }
}
EOF

agentapi-proxy client schedule create -f schedule.json
Recurring Execution (Cron)
cat > schedule-cron.json <<'EOF'
{
  "name": "Daily Standup Bot",
  "cron_expr": "0 9 * * 1-5",
  "timezone": "America/New_York",
  "session_config": {
    "tags": {
      "repository": "org/standup-bot",
      "type": "standup"
    },
    "params": {
      "message": "Generate daily standup report"
    },
    "environment": {
      "SLACK_WEBHOOK": "https://hooks.slack.com/..."
    }
  }
}
EOF

agentapi-proxy client schedule create -f schedule-cron.json

Timezone Support:

  • timezone: IANA timezone name (e.g., "America/New_York", "Europe/London", "Asia/Tokyo")
  • Default: "Asia/Tokyo"
  • The cron expression is evaluated in the specified timezone

Common Cron Expressions:

  • 0 9 * * 1-5 - Every weekday at 9:00 AM
  • 0 */6 * * * - Every 6 hours
  • 0 0 * * 0 - Every Sunday at midnight
  • 30 14 1 * * - First day of every month at 2:30 PM

Response:

{
  "id": "schedule-abc123",
  "name": "Daily Standup Bot",
  "status": "active",
  "cron_expr": "0 9 * * 1-5",
  "created_at": "2024-01-01T12:00:00Z",
  "next_run": "2024-01-02T09:00:00Z"
}

Listing Schedules

# List all schedules
agentapi-proxy client schedule list

# Note: Filtering by status, scope, or team is done by the API automatically
# based on your authentication and permissions

Getting a Specific Schedule

agentapi-proxy client schedule get SCHEDULE_ID

Updating a Schedule

# Update specific fields using apply (patch)
echo '{"status":"paused"}' | agentapi-proxy client schedule apply SCHEDULE_ID

# Or update multiple fields
cat > update.json <<'EOF'
{
  "name": "Updated Schedule Name",
  "status": "paused",
  "cron_expr": "0 10 * * 1-5"
}
EOF

cat update.json | agentapi-proxy client schedule apply SCHEDULE_ID

Deleting a Schedule

agentapi-proxy client schedule delete SCHEDULE_ID

Manually Triggering a Schedule

Note: The trigger command is not yet implemented in the CLI client. Use the API directly if you need to manually trigger a schedule:

curl -X POST https://api.example.com/schedules/SCHEDULE_ID/trigger \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "triggered_at": "2024-01-02T15:30:00Z"
}

Use Cases

1. Daily Reports

{
  "name": "Daily Team Report",
  "cron_expr": "0 17 * * 1-5",
  "session_config": {
    "tags": {
      "type": "report",
      "team": "engineering"
    },
    "params": {
      "message": "Generate end-of-day team report"
    }
  }
}

2. Weekly Code Reviews

{
  "name": "Weekly PR Review",
  "cron_expr": "0 10 * * 1",
  "session_config": {
    "tags": {
      "repository": "org/main-repo",
      "type": "code-review"
    },
    "params": {
      "message": "Review all open PRs from last week"
    }
  }
}

3. Incident Response Drills

{
  "name": "Monthly Incident Drill",
  "cron_expr": "0 14 1 * *",
  "session_config": {
    "tags": {
      "type": "incident-drill",
      "team": "sre"
    },
    "params": {
      "message": "Run incident response drill"
    }
  }
}

4. Delayed Task Execution

{
  "name": "Deploy After Hours",
  "scheduled_at": "2025-01-15T22:00:00Z",
  "session_config": {
    "tags": {
      "repository": "org/production",
      "type": "deployment"
    },
    "params": {
      "message": "Deploy version 2.0 to production"
    }
  }
}

Schedule Status

  • active: Schedule is enabled and will execute at the specified time
  • paused: Schedule is temporarily disabled
  • completed: One-time schedule that has already executed

Access Control

  • User Scope: Only the creating user can access and manage the schedule
  • Team Scope: All team members can access and manage the schedule
  • Admin: Can view and manage all schedules

Template Variables

For schedule sessions, the memory_key map values support Go template rendering with schedule context variables:

  • {{.schedule_id}}: Unique identifier of the schedule
  • {{.schedule_name}}: Human-readable name of the schedule
  • {{.timezone}}: Schedule timezone (IANA format, e.g., Asia/Tokyo)

Example:

{
  "memory_key": {
    "schedule_ref": "{{.schedule_id}}",
    "schedule_name": "{{.schedule_name}}"
  }
}

Note: The params.message field uses static text for schedules, not template rendering. Use the memory_key for dynamic references.

For the complete template variables reference including all available functions, see TEMPLATE_VARIABLES.md.

Reference Documentation

For complete API endpoint documentation and permissions, see:

External Session Manager (ESM)

An ESM lets a parent agentapi-proxy route sessions to another machine. Native ESMs use outbound allocation polling, so the parent does not need inbound access for allocation. The parent must still be able to reach the ESM's public_url for session traffic.

user -> parent /start -> allocation queue
                         ^ outbound polling by ESM
user -> parent /:sessionId/* -> HMAC-signed proxy -> ESM public_url

Native Linux/macOS installation (recommended)

Use the one-command installer. It registers the host, installs and starts the daemon, then verifies local health and the parent heartbeat.

export AGENTAPI_KEY="<parent-proxy-api-key>"

sudo --preserve-env=AGENTAPI_KEY agentapi-proxy native install \
  --upstream https://parent-proxy.example.com \
  --public-url http://10.0.0.10:8080 \
  --name native-builder-01 \
  --label pool=native \
  --label machine=native-builder-01

On macOS, omit sudo; the command installs a per-user LaunchAgent. Prefer --api-key-stdin or --api-key-file if preserving the environment is undesirable. The API key is used only for registration and is not saved in daemon configuration.

Installation is idempotent: a stable instance ID is kept, registration and service configuration are updated on subsequent runs, and the connection token is preserved. The installer automatically detects os, arch, and hostname labels.

Lifecycle commands

agentapi-proxy native status
agentapi-proxy native doctor
agentapi-proxy native restart
agentapi-proxy native rotate-token
agentapi-proxy native uninstall

Linux stores configuration under /etc/agentapi-native, state under /var/lib/agentapi-native, and the managed executable under /usr/local/libexec/agentapi-proxy. macOS uses ~/Library/Application Support/agentapi-native and ~/Library/LaunchAgents/com.agentapi.native.plist.

Native sessions are not sandboxed. Use a dedicated host for one user or a mutually trusted team. Each session has an isolated directory beneath <state-dir>/sessions/<session-id>; deleting the public session terminates its process group and removes that directory.

Registration API

The CLI is preferred for installation, but the parent API supports complete ESM management. These endpoints currently require direct REST calls; the agentapi-proxy client has no ESM subcommand.

PARENT_PROXY_URL="https://parent-proxy.example.com"
API_KEY="<parent-proxy-api-key>"

# Idempotently register by stable instance_id. connection_token is returned only
# on creation or explicit rotation.
curl -X POST "$PARENT_PROXY_URL/external-session-managers" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "instance_id": "host-stable-id",
    "name": "native-builder-01",
    "scope": "user",
    "labels": {"pool":"native", "os":"linux"},
    "default": false,
    "public_url": "http://10.0.0.10:8080"
  }'

curl -H "X-API-Key: $API_KEY" \
  "$PARENT_PROXY_URL/external-session-managers?scope=user"

curl -X PATCH "$PARENT_PROXY_URL/external-session-managers/<manager-id>" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"instance_id":"host-stable-id","name":"native-builder-01","labels":{"pool":"build"}}'

curl -X POST -H "X-API-Key: $API_KEY" \
  "$PARENT_PROXY_URL/external-session-managers/<manager-id>/rotate-token"

curl -X DELETE -H "X-API-Key: $API_KEY" \
  "$PARENT_PROXY_URL/external-session-managers/<manager-id>"

For team ownership, set scope=team and include team_id in registration and list requests. Treat connection_token as a secret; it is returned once on creation or rotation. GET /external-session-managers/{id} exposes only has_connection_token, not the token value.

The daemon sends POST /external-session-managers/{id}/heartbeat with its connection token. The parent verifies that public_url/healthz is reachable. HTTP 401 means the token is invalid; HTTP 424 means the public URL is unreachable.

Routing sessions

Manager labels are selected with allocator.* session tags. Multiple tags use AND semantics, and allocator.id selects one manager exactly.

curl -X POST "$PARENT_PROXY_URL/start" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "tags": {"allocator.pool":"native", "allocator.os":"linux"},
    "params": {"message":"Run the build", "agent_type":"codex-acp"}
  }'

If a manager has default: true, sessions without allocator tags may route to it.

Kubernetes ESM (advanced)

For a Kubernetes-backed ESM, run the normal agentapi-proxy server with Kubernetes provisioning enabled. Register it first to obtain the connection token, then configure:

export SESSION_MANAGER_ENABLED=true
export SESSION_MANAGER_UPSTREAM_URL="https://parent-proxy.example.com"
export SESSION_MANAGER_CONNECTION_TOKEN="<connection-token>"
export SESSION_MANAGER_HMAC_SECRET="<connection-token>"
export SESSION_MANAGER_PUBLIC_URL="https://esm.example.com"
export AGENTAPI_K8S_SESSION_PROVISIONER_PROXY_URL="https://esm.example.com"

The same token authenticates outbound allocator polling and verifies HMAC-signed proxy requests. SESSION_MANAGER_PUBLIC_URL must be reachable from the parent, and provisioned session pods must call the ESM through AGENTAPI_K8S_SESSION_PROVISIONER_PROXY_URL.

Verification and troubleshooting

After /start, query the returned session through the parent:

curl -H "X-API-Key: $API_KEY" "$PARENT_PROXY_URL/<session-id>/status"
  • Run agentapi-proxy native doctor first for native installations.
  • 503 External session manager has not reported a routable session yet: verify the ESM public URL and heartbeat.
  • 404 Session not found: verify that the ESM reports the concrete local session ID.
  • invalid signature: rotate/reinstall credentials and confirm the connection token is also used as SESSION_MANAGER_HMAC_SECRET.
  • Heartbeat 424: ensure the parent can reach <public_url>/healthz.
  • Native ESM logs and status should show successful outbound polling to the parent.

SlackBot Management

This skill provides guidance for managing agentapi-proxy SlackBots that automatically create sessions in response to Slack events.

Overview

SlackBots enable automatic session creation when events occur in Slack. Each SlackBot has:

  • Name: Descriptive name for the SlackBot
  • Scope: User-level or team-level access
  • Bot Token: Kubernetes secret containing the Slack bot token
  • Channel Filters: Optional list of allowed channel names
  • Session Config: Environment variables, tags, and initial messages for created sessions

SlackBots use Socket Mode (WebSocket) to receive events from Slack, eliminating the need for public webhook endpoints.

Core Workflows

Creating a SlackBot

Basic SlackBot
cat > slackbot-basic.json <<'EOF'
{
  "name": "My Slack Bot",
  "session_config": {
    "initial_message_template": "New Slack message from {{.event.user}} in <#{{.event.channel}}>: {{.event.text}}"
  }
}
EOF

agentapi-proxy client slackbot create -f slackbot-basic.json
Team-Scoped SlackBot with Channel and Event Filters
cat > slackbot-team.json <<'EOF'
{
  "name": "Team Bot",
  "scope": "team",
  "team_id": "myorg/backend",
  "bot_token_secret_name": "my-slack-bot-token",
  "bot_token_secret_key": "bot-token",
  "allowed_channel_names": ["dev", "backend"],
  "allowed_event_types": ["message", "app_mention"],
  "notify_on_session_created": true,
  "allow_bot_messages": false,
  "max_sessions": 10,
  "session_config": {
    "initial_message_template": "{{.event.text}}",
    "tags": {
      "channel": "{{.event.channel}}"
    }
  }
}
EOF

agentapi-proxy client slackbot create -f slackbot-team.json

Fields:

  • name (required): SlackBot name
  • scope: user (default) or team
  • team_id: Required when scope is team
  • bot_token_secret_name: Kubernetes secret name containing the bot token
  • bot_token_secret_key: Key within the secret containing the bot token (default: "bot-token")
  • bot_token: Direct bot token (xoxb-...) - alternative to secret reference
  • app_token: Direct app-level token for Socket Mode (xapp-...) - alternative to secret reference
  • allowed_channel_names: Optional list of allowed channel names (without #). Supports partial matching. If omitted, all channels are allowed.
  • allowed_event_types: Optional list of Slack event types to process (e.g., ["message", "app_mention"]). If omitted, all event types are allowed.
  • notify_on_session_created: Post a notification message with the session URL when a session is created (default: true)
  • allow_bot_messages: Process messages from other bots (default: false)
  • max_sessions: Maximum concurrent sessions (default: 10)
  • session_config: Configuration for created sessions
    • initial_message_template: Go template for new thread sessions
    • reuse_message_template: Go template for messages sent to existing thread sessions
    • tags: Tags to apply to created sessions (supports Go template values)
    • environment: Environment variables for the session (supports Go template values)
    • params: SlackBotSessionParams
      • agent_type: Agent type (e.g., "claude-agentapi")
      • oneshot: Auto-delete session after response (default: false)

Response:

{
  "id": "slackbot-abc123",
  "name": "Team Bot",
  "status": "active",
  "scope": "team",
  "team_id": "myorg/backend",
  "owner_id": "alice",
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

Listing SlackBots

# List all SlackBots
agentapi-proxy client slackbot list

# Note: Filtering by status, scope, or team is done by the API automatically
# based on your authentication and permissions

Getting a Specific SlackBot

agentapi-proxy client slackbot get SLACKBOT_ID

Updating a SlackBot

# Update specific fields using apply (patch)
echo '{"status":"inactive"}' | agentapi-proxy client slackbot apply SLACKBOT_ID

# Or update multiple fields
cat > update.json <<'EOF'
{
  "name": "Updated Bot Name",
  "status": "inactive",
  "allowed_channel_names": ["dev", "backend", "general"]
}
EOF

cat update.json | agentapi-proxy client slackbot apply SLACKBOT_ID

Note: Omitted fields are not changed.

Deleting a SlackBot

agentapi-proxy client slackbot delete SLACKBOT_ID

Use Cases

1. Support Bot

Automatically create sessions when users post in a support channel:

{
  "name": "Support Bot",
  "allowed_channel_names": ["support", "help"],
  "session_config": {
    "initial_message_template": "Support request from {{.event.user}}: {{.event.text}}",
    "tags": {
      "type": "support",
      "channel": "{{.event.channel}}"
    }
  }
}

2. Code Review Bot

Create sessions for code review requests:

{
  "name": "Code Review Bot",
  "allowed_channel_names": ["code-review"],
  "session_config": {
    "initial_message_template": "Review request: {{.event.text}}",
    "tags": {
      "type": "code-review",
      "user": "{{.event.user}}"
    }
  }
}

3. Team Incident Bot

Team-scoped bot for incident response:

{
  "name": "Incident Bot",
  "scope": "team",
  "team_id": "myorg/sre",
  "allowed_channel_names": ["incidents"],
  "session_config": {
    "initial_message_template": "Incident alert: {{.event.text}}",
    "tags": {
      "type": "incident",
      "severity": "high"
    },
    "environment": {
      "PAGERDUTY_TOKEN": "pd_token"
    }
  }
}

Template Variables

The initial_message_template and reuse_message_template support Go template syntax with access to Slack event data:

Common variables:

  • {{.event.type}}: Event type (e.g., "message", "app_mention")
  • {{.event.subtype}}: Event subtype (e.g., "bot_message")
  • {{.event.user}}: User ID who triggered the event
  • {{.event.channel}}: Channel ID where the event occurred
  • {{.event.text}}: Message text
  • {{.event.ts}}: Event timestamp
  • {{.event.thread_ts}}: Thread timestamp (for threaded messages)
  • {{.event.bot_id}}: Bot ID (if sent by a bot)
  • {{.team_id}}: Slack workspace team ID
  • {{.thread_messages}}: Full thread context (all messages in thread)
  • {{.bot_id}}: SlackBot ID

Slack formatting:

  • <@{{.event.user}}>: Mention user
  • <#{{.event.channel}}>: Link to channel

Example:

New message from <@{{.event.user}}> in <#{{.event.channel}}>: {{.event.text}}

For the complete template variables reference including all available functions, see TEMPLATE_VARIABLES.md.

Bot Token Setup

SlackBots require a Slack bot token and app-level token. There are two ways to provide them:

Method 1: Kubernetes Secret (Recommended)

  1. Create a Slack App at https://api.slack.com/apps
  2. Enable Socket Mode and generate an App-Level Token with connections:write scope
  3. Install the app to your workspace and note the Bot User OAuth Token
  4. Create a Kubernetes secret:
kubectl create secret generic my-slack-bot-token \
  --from-literal=bot-token=xoxb-your-bot-token \
  --from-literal=app-token=xapp-your-app-token
  1. Reference the secret in your SlackBot configuration:
cat > slackbot-with-secret.json <<'EOF'
{
  "name": "My Slack Bot",
  "bot_token_secret_name": "my-slack-bot-token",
  "bot_token_secret_key": "bot-token",
  "session_config": {
    "initial_message_template": "{{.event.text}}"
  }
}
EOF

agentapi-proxy client slackbot create -f slackbot-with-secret.json

Method 2: Direct Token Provision

Provide tokens directly in the request (they will be stored in a Kubernetes secret automatically):

cat > slackbot-with-tokens.json <<'EOF'
{
  "name": "My Slack Bot",
  "bot_token": "xoxb-your-bot-token",
  "app_token": "xapp-your-app-token",
  "session_config": {
    "initial_message_template": "{{.event.text}}"
  }
}
EOF

agentapi-proxy client slackbot create -f slackbot-with-tokens.json

Note: Tokens are write-only and will not be returned in GET requests for security.

Access Control

  • User Scope: Only the creating user can access and manage the SlackBot
  • Team Scope: All team members can access and manage the SlackBot
  • Admin: Can view and manage all SlackBots

Reference Documentation

For complete API endpoint documentation and permissions, see:

Webhook Management

This skill provides guidance for managing agentapi-proxy webhooks that automatically create sessions in response to external events.

⚠️ Important: Always Use This Skill for Webhook Operations

When performing any webhook-related operations (creating, updating, listing, deleting, or modifying webhook configurations), always invoke this skill first rather than directly using curl or API calls.

This ensures:

  • Proper authentication and API endpoint configuration
  • Correct payload structure and validation
  • Access to up-to-date examples and best practices
  • Consistent error handling and guidance

Overview

Webhooks enable automatic session creation when events occur in external systems (GitHub, Slack, Datadog, custom services). Each webhook has:

  • Triggers: Rules that determine when to create a session
  • Conditions: Filters based on event properties
  • Session Config: Environment variables, tags, and initial messages for created sessions

Core Workflows

Creating a Webhook

GitHub Webhook

First, create a JSON file with your webhook configuration:

cat > webhook-github.json <<'EOF'
{
  "name": "Pull Request Reviewer",
  "type": "github",
  "github": {
    "allowed_events": ["pull_request"],
    "allowed_repositories": ["owner/repo"]
  },
  "triggers": [
    {
      "name": "PR opened",
      "enabled": true,
      "conditions": {
        "github": {
          "events": ["pull_request"],
          "actions": ["opened"],
          "draft": false
        }
      },
      "session_config": {
        "initial_message_template": "Review PR #{{.pull_request.number}}: {{.pull_request.title}}",
        "tags": {
          "repository": "{{.repository.full_name}}",
          "pr": "{{.pull_request.number}}"
        },
        "reuse_session": false,
        "mount_payload": false
      }
    }
  ],
  "max_sessions": 10,
  "signature_type": "hmac",
  "signature_header": "X-Hub-Signature-256",
  "signature_prefix": "sha256="
}
EOF

agentapi-proxy client webhook create -f webhook-github.json
Custom Webhook (Slack, Datadog, Sentry, etc.)
cat > webhook-custom.json <<'EOF'
{
  "name": "Slack Incident Alerts",
  "type": "custom",
  "triggers": [
    {
      "name": "Critical incident",
      "conditions": {
        "go_template": "{{ and (eq .event.type \"incident\") (eq .event.severity \"critical\") }}"
      },
      "session_config": {
        "initial_message_template": "Incident: {{.event.title}}",
        "tags": {
          "source": "slack",
          "severity": "{{.event.severity}}"
        }
      }
    }
  ],
  "max_sessions": 5,
  "signature_type": "hmac",
  "signature_header": "X-Signature"
}
EOF

agentapi-proxy client webhook create -f webhook-custom.json

For Static Token Verification (e.g., Sentry):

cat > webhook-sentry.json <<'EOF'
{
  "name": "Sentry Error Alerts",
  "type": "custom",
  "secret": "your-static-secret-token",
  "signature_type": "static",
  "signature_header": "X-Sentry-Token",
  "triggers": [
    {
      "name": "Error event",
      "conditions": {
        "go_template": "{{ eq .event.level \"error\" }}"
      },
      "session_config": {
        "initial_message_template": "Sentry error: {{.event.title}}"
      }
    }
  ]
}
EOF

agentapi-proxy client webhook create -f webhook-sentry.json

Response:

{
  "id": "webhook-123",
  "webhook_url": "https://api.example.com/hooks/github/webhook-123",
  "secret": "generated-secret-key"
}

Listing Webhooks

agentapi-proxy client webhook list

Getting a Specific Webhook

agentapi-proxy client webhook get WEBHOOK_ID

Updating a Webhook

# Update specific fields using apply (patch)
echo '{"max_sessions":15}' | agentapi-proxy client webhook apply WEBHOOK_ID

# Or update multiple fields
cat > update.json <<'EOF'
{
  "name": "Updated Webhook Name",
  "status": "active"
}
EOF

cat update.json | agentapi-proxy client webhook apply WEBHOOK_ID

Deleting a Webhook

agentapi-proxy client webhook delete WEBHOOK_ID

Regenerating Webhook Secret

agentapi-proxy client webhook regenerate-secret WEBHOOK_ID

Testing a Webhook

Note: The test or trigger command is not yet implemented in the CLI client. Use the API directly if you need to test a webhook:

# Dry run (test without creating a session)
curl -X POST https://api.example.com/webhooks/WEBHOOK_ID/trigger \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "event": "test_event",
      "severity": "critical"
    },
    "dry_run": true
  }'

# Actual trigger (create a session)
curl -X POST https://api.example.com/webhooks/WEBHOOK_ID/trigger \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "event": "test_event",
      "severity": "critical"
    },
    "dry_run": false
  }'

Advanced Configuration

Signature Verification

Webhooks support two types of signature verification:

1. HMAC Signature (default)

{
  "signature_type": "hmac",
  "signature_header": "X-Hub-Signature-256",
  "signature_prefix": "sha256="
}

The webhook validates HMAC signatures automatically. The signature_prefix is auto-detected but can be explicitly set:

  • GitHub: sha256=
  • Slack: v0=
  • Custom: any prefix or empty string

2. Static Token

{
  "signature_type": "static",
  "signature_header": "X-Custom-Token",
  "secret": "your-static-token"
}

The webhook compares the header value directly against the secret.

Concurrency Control

Limit the number of concurrent sessions created by a webhook:

{
  "max_sessions": 10
}

Default: 10, Maximum: 100. When the limit is reached, new webhook events are queued.

Session Reuse

Reuse existing sessions instead of creating new ones:

{
  "session_config": {
    "reuse_session": true,
    "reuse_message_template": "New event: {{.event.title}}"
  }
}

When reuse_session is enabled:

  • If an active session exists matching the same tags, send a new message to it
  • If no session exists, create a new one with initial_message_template
  • Use reuse_message_template for messages sent to existing sessions

Mount Webhook Payload

Mount the webhook payload as a file in the container:

{
  "session_config": {
    "mount_payload": true
  }
}

The payload will be available at /webhook-payload.json in the session container.

Reference Documentation

For detailed information, see:

Sponsors

Details

Marketplace
takutakahashi/marketplace
Source
plugins/ccplant
Author
takutakahashi
Category
Developer Tools
License
MIT
Keywords
agentapi, api, authentication, session-management, webhooks, automation