
ccplant
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-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add takutakahashi/marketplace.
Contents
Discovered from sourceSkills 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 |
asset | HTML asset アップロード | create |
schedule | スケジュール管理 | create / list / get / apply / delete |
webhook | Webhook 管理 | create / list / get / apply / delete / regenerate-secret |
slackbot | SlackBot 管理 | 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:
- API_REFERENCE.md - Complete endpoint reference
- AUTHENTICATION.md - Authentication methods and configuration
- PERMISSIONS.md - Role-based access control details
- TASK_REFERENCE.md - Task management API reference
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:
- Split work into bounded tasks with minimal overlap.
- State the expected artifact, relevant paths, constraints, and completion checks for each task.
- Identify dependencies. Start dependent work only after its prerequisite result is available.
- Assign a distinct branch or non-overlapping file ownership when sessions will edit the same repository.
- 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:
- Read the final history; do not infer success from status alone.
- Verify claimed files, commits, PRs, and test results in the authoritative repository.
- Send a focused follow-up if evidence is missing or the output does not meet the assignment.
- Resolve conflicting recommendations in the parent session.
- Integrate results in dependency order and run the combined verification.
- 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
401or403, 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 パラメータを指定すると、以下が自動実行されます:
/tmp/check/CYCLE_ENABLEDにcycle_messageの内容が書き込まれる(セッション起動時に作成)- Stop hook に
agentapi-proxy client cycleが登録される(メッセージ引数なし) - エージェントが停止するたびに hook が発火→
CYCLE_ENABLEDを読んで送信
API パラメータ
| パラメータ | 型 | 説明 |
|---|---|---|
cycle_message | string | /tmp/check/CYCLE_ENABLED に書き込まれるメッセージ。空の場合は cycle 無効 |
cycle_max_count | int | 最大繰り返し回数(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.log | cycle コマンドの実行ログ |
カウンターの動作
- カウンターはメッセージ送信前にインクリメントされます
/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 AM0 */6 * * *- Every 6 hours0 0 * * 0- Every Sunday at midnight30 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.messagefield uses static text for schedules, not template rendering. Use thememory_keyfor 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:
- API_REFERENCE.md - Complete schedule API reference
- PERMISSIONS.md - Role-based access control details
- TEMPLATE_VARIABLES.md - Go template variables reference
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 doctorfirst 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 asSESSION_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 namescope:user(default) orteamteam_id: Required whenscopeisteambot_token_secret_name: Kubernetes secret name containing the bot tokenbot_token_secret_key: Key within the secret containing the bot token (default: "bot-token")bot_token: Direct bot token (xoxb-...) - alternative to secret referenceapp_token: Direct app-level token for Socket Mode (xapp-...) - alternative to secret referenceallowed_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 sessionsinitial_message_template: Go template for new thread sessionsreuse_message_template: Go template for messages sent to existing thread sessionstags: Tags to apply to created sessions (supports Go template values)environment: Environment variables for the session (supports Go template values)params: SlackBotSessionParamsagent_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)
- Create a Slack App at https://api.slack.com/apps
- Enable Socket Mode and generate an App-Level Token with
connections:writescope - Install the app to your workspace and note the Bot User OAuth Token
- 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
- 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:
- API_REFERENCE.md - Complete SlackBot API reference
- PERMISSIONS.md - Role-based access control details
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_templatefor 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:
- WEBHOOK_REFERENCE.md - Complete webhook API and configuration
- WEBHOOK_TRIGGERS.md - Trigger conditions and filtering
- WEBHOOK_EXAMPLES.md - Integration examples for various services
- TEMPLATE_VARIABLES.md - Go template variables reference for all contexts
Sponsors
Details
- Marketplace
- takutakahashi/marketplace
- Source
- plugins/ccplant
- Author
- takutakahashi
- Category
- Developer Tools
- License
- MIT
- Keywords
- agentapi, api, authentication, session-management, webhooks, automation