外部API連携

概要

Captain.AIは、パーソナルアクセストークン（PAT）を使用して外部からAPIにアクセスする機能を提供します。スクリプトや外部アプリケーションから、Captain.AIのチャット機能を利用できます。

注意: このAPIは、メッセージを送信してエージェントに処理を依頼するためのものです。チャット画面のようにエージェントと対話を続けることはできません。1回のリクエストにつき1回の処理が実行されます。

---

パーソナルアクセストークン（PAT）の取得

APIにアクセスするには、まずPATを取得する必要があります。

手順

1. Captain.AIにログインします
2. ユーザー設定 > パーソナルアクセストークン を開きます
3. 「新規作成」をクリックします
4. 生成されたトークンをコピーします

重要: トークンは作成時のみ表示されます。必ずコピーして安全な場所に保管してください。

---

チャットAPIの利用

PATを使用して、外部からチャットメッセージを送信できます。

エンドポイント

POST /api/external/chat

認証

HTTPリクエストヘッダーにPATを含めます：

Authorization: Bearer <your-personal-access-token>

リクエストパラメータ

パラメータ	必須	説明
agent_goal_id	はい	使用するエージェントのID
message	いいえ	エージェントに送信するメッセージ
name	いいえ	会話の表示名
files	いいえ	添付ファイル（multipart/form-data使用時のみ）

リクエスト例（テキストのみ）

curl -X POST https://<captain-ui-url>/api/external/chat \
  -H "Authorization: Bearer <your-personal-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, Captain!",
    "agent_goal_id": "<agent-goal-id>"
  }'

リクエスト例（ファイル添付）

ファイルを添付する場合は、multipart/form-data 形式で送信します。

curl -X POST https://<captain-ui-url>/api/external/chat \
  -H "Authorization: Bearer <your-personal-access-token>" \
  -F "agent_goal_id=<agent-goal-id>" \
  -F "message=このファイルを分析してください" \
  -F "files=@/path/to/document.pdf" \
  -F "files=@/path/to/data.csv"

注意: 複数ファイルを添付する場合は、files フィールドを複数回指定します。

レスポンス

APIはリクエストを受け付けると、会話IDと処理ステータスを返します。

---

活用例

CI/CDパイプラインからの利用

# ビルド結果をCaptainに報告
curl -X POST https://<captain-ui-url>/api/external/chat \
  -H "Authorization: Bearer $CAPTAIN_PAT" \
  -H "Content-Type: application/json" \
  -d "{
    \"message\": \"ビルド結果: ${BUILD_STATUS}\",
    \"agent_goal_id\": \"${AGENT_GOAL_ID}\"
  }"

Pythonスクリプトからの利用（テキストのみ）

import requests

CAPTAIN_URL = "https://<captain-ui-url>"
PAT = "<your-personal-access-token>"
AGENT_GOAL_ID = "<agent-goal-id>"

response = requests.post(
    f"{CAPTAIN_URL}/api/external/chat",
    headers={"Authorization": f"Bearer {PAT}"},
    json={
        "message": "データ分析を実行してください",
        "agent_goal_id": AGENT_GOAL_ID,
    },
)

print(response.json())

Pythonスクリプトからの利用（ファイル添付）

import requests

CAPTAIN_URL = "https://<captain-ui-url>"
PAT = "<your-personal-access-token>"
AGENT_GOAL_ID = "<agent-goal-id>"

with open("report.txt", "rb") as f:
    response = requests.post(
        f"{CAPTAIN_URL}/api/external/chat",
        headers={"Authorization": f"Bearer {PAT}"},
        data={
            "agent_goal_id": AGENT_GOAL_ID,
            "message": "このレポートを要約してください",
        },
        files=[("files", ("report.txt", f, "text/plain"))],
    )

print(response.json())

---

セキュリティに関する注意事項

• PATは機密情報です。ソースコードにハードコーディングしないでください
• 環境変数やシークレット管理ツールを使用してPATを管理してください
• 不要になったPATは速やかに無効化してください
• PATが漏洩した可能性がある場合は、直ちに無効化し新しいトークンを生成してください