Task Interface

1つのエンドポイント。自然な言葉。あとはすべてエージェントが処理します。

---

何が変わるのか

従来のインテグレーションでは、エンドポイントを学び、フィールドをマッピングし、スキーマをバージョン管理し、あらゆるエッジケースに対処する必要がありました。チャットエージェントゲートウェイはそのすべてをエージェント型コミュニケーションに置き換えます。必要なことを説明してください。SOIS 自身のエージェントが意図を解釈し、詳細を調整し、ワークスペース全体で実行し、結果を返信します。これは、自前の AI を持たない呼び出し元のための入り口です。すでにエージェントをお持ちの場合は、代わりに MCP サーバー経由で直接接続してください。

コネクターも、ミドルウェアも、サードパーティの自動化レイヤーも不要です。

---

認証

すべてのメッセージには2つの認証情報が必要です。

なぜ2つなのか。 トークンは身元を証明し、キーは支出を制御します。どちらか一方だけが漏えいしても、もう一方がなければ役に立ちません。1人のユーザーが、インテグレーションごとに異なる予算を持つ複数のキーを保有できます。

両方とも Sois AI ワークスペースの Settings から取得します。

---

メッセージを送信する

POST /api/agent

Headers

Authorization: Bearer <your_token>
X-Api-Key: sois_...
Content-Type: application/json

Body

例

curl -X POST "https://your-workspace.sois.ai/api/agent" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Api-Key: sois_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Create a contact for John Smith at Acme Corp, [email protected], +44 7700 900000",
    "context": { "entity_type": "contact", "action": "create" }
  }'

レスポンス 202 Accepted

{
    "conversation_uuid": "6cafd8ba-dd51-4411-808e-671d1dd59561",
    "status": "accepted",
    "message": "Your request has been queued."
}

メッセージはゲートウェイに入りました。ここから先はエージェントが引き受けます。

---

返信を受け取る

選択肢は2つです。Webhook を待つ か、会話をポーリングする かです。

オプション1: Webhook（推奨）

キーに response_url がある場合、完了するとエージェントが結果を直接配信します。署名済みで、検証済みで、ポーリングは不要です。

POST https://your-app.com/webhook
Content-Type: application/json
X-Signature: <hmac_sha256>
X-Conversation-UUID: 6cafd8ba-...

Resolved:

{
    "conversation_uuid": "6cafd8ba-...",
    "status": "resolved",
    "response": "Contact created: John Smith, Acme Corp, [email protected], +44 7700 900000."
}

Failed:

{
    "conversation_uuid": "6cafd8ba-...",
    "status": "failed",
    "error": "An error occurred while processing your request."
}

オプション2: 会話をポーリングする

GET /api/agent/{conversation_uuid}

Authorization: Bearer <your_token>
X-Api-Key: sois_...

レスポンス 200 OK:

{
    "conversation_uuid": "6cafd8ba-...",
    "status": "resolved",
    "turns": [
        {
            "role": "user",
            "payload": { "message": "Find all contacts from London" },
            "timestamp": "2026-02-12T01:07:03+00:00"
        },
        {
            "role": "agent",
            "payload": {
                "content": "I found 12 contacts based in London..."
            },
            "timestamp": "2026-02-12T01:07:13+00:00"
        }
    ],
    "webhook": {
        "status": "delivered",
        "delivered_at": "2026-02-12T01:07:14+00:00"
    },
    "resolved_at": "2026-02-12T01:07:13+00:00",
    "expires_at": "2026-02-13T01:07:03+00:00",
    "created_at": "2026-02-12T01:07:03+00:00"
}

会話のステータス

---

Webhook 署名の検証

すべての Webhook は、キーの signing secret を使って HMAC-SHA256 で署名されます。処理の前に必ず検証してください。

Python:

import hmac, hashlib

expected = hmac.new(
    key=your_signing_secret.encode(),
    msg=raw_request_body.encode(),
    digestmod=hashlib.sha256
).hexdigest()

assert expected == request.headers['X-Signature']

Node.js:

const crypto = require('crypto');
const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(rawBody)
    .digest('hex');

if (expected !== req.headers['x-signature']) {
    throw new Error('Invalid signature');
}

PHP:

$expected = hash_hmac('sha256', $rawBody, $signingSecret);
if (!hash_equals($expected, $request->header('X-Signature'))) {
    abort(403, 'Invalid signature');
}

---

会話の例

エージェントは Sois AI ワークスペースに完全にアクセスできます。たとえば次のようなことを頼めます。

検索:

{ "message": "Find all contacts from London" }

作成:

{
    "message": "Create a contact: Jane Doe, CEO of Acme Corp, [email protected]",
    "context": { "entity_type": "contact", "action": "create" }
}

メール:

{
    "message": "Send an email to [email protected] introducing our new product line",
    "context": { "entity_type": "inbox", "action": "compose" }
}

タスク:

{
    "message": "Create a task: Research competitor pricing for Q1 2026",
    "context": { "entity_type": "task", "action": "create" }
}

要約:

{
    "message": "Give me a full summary of this contact",
    "context": { "entity_type": "contact", "entity_id": "abc-123", "action": "summarize" }
}

複数ステップ:

{ "message": "Find the Q1 report, summarise it, and email the summary to the sales team" }

エージェントは曖昧さを調整します。動作する前に検索が必要なら検索します。複数のレコードが一致する場合は、最適なものを選び、その理由を伝えます。厳格なスキーマはなく、あるのは意図だけです。

---

キーの管理

キーは Sois AI ワークスペースの Settings > API Keys から、またはプログラムから管理します。

キーを作成する

POST /api/api-keys

{
    "label": "My CRM Integration",
    "response_url": "https://your-app.com/webhook",
    "budget_usd_cents": 5000,
    "budget_period": "monthly"
}

レスポンスには、キー（1回だけ 表示されるので、すぐにコピーしてください）と、Webhook 検証用の signing secret が含まれます。

キーを管理する

---

予算の制御

従来のインテグレーションは、恣意的なレート制限であなたを抑制しました。毎分100リクエスト、1日10,000件などです。チャットエージェントゲートウェイはドルを使います。

キーごとに予算を設定します。エージェントはアクションごとに credit を請求します。各インテグレーションの価値はあなたが決めます。

予算を超過すると、メッセージは 429 を、難解なエラーコードではなく明確な説明とともに返します。

---

エラー

すべてのエラーは同じ形式に従います。

{
    "error": {
        "code": "ERROR_CODE",
        "message": "A clear, human-readable explanation."
    }
}

---

制限