文件

聊天端點

以程式設計方式向你的代理程式傳送訊息並接收 AI 回應。

聊天端點可讓你向代理程式傳送訊息並接收 AI 回應。你可以用它建立自訂聊天介面，或將代理程式功能整合進自己的應用程式。

端點

POST /api/v1/chat

身分驗證

需要 Bearer 權杖驗證。

Authorization: Bearer YOUR_API_KEY

請求主體

{
  "chatbotId": "uuid",
  "messages": [
    { "role": "user", "content": "What are your pricing plans?" }
  ],
  "conversationId": "optional-id",
  "stream": false
}

參數

欄位類型是否必填說明
chatbotIdstring（UUID）是你的代理程式 ID
messagesarray是訊息物件陣列（1 到 100 項）
conversationIdstring（最多 16 字元）否前一次呼叫的 x-conversation-id 標頭所回傳的參考 ID。無效或缺少此值時，伺服器會指派一組新的 ID。
streamboolean否啟用串流回應（預設：false）

訊息物件

欄位類型值說明
rolestring"user"、"assistant"訊息發送者
contentstring1 到 32,000 字元訊息內容

限制

  • 每個請求最多 100 則訊息
  • 每則訊息最多 32,000 字元

回應

非串流（預設）

成功（200）：

{
  "text": "Our pricing starts at $29.99/month for the Hobby plan..."
}

回應標頭包含：

X-Conversation-ID: abc123

串流

設定 "stream": true 以啟用串流回應。

成功（200）：

Content-Type: text/plain; charset=utf-8

回應會在生成的同時以純文字串流傳送。適合用於即時 UI 更新。

請求範例

基本請求

curl -X POST 'https://your-domain.com/api/v1/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000",
    "messages": [
      {"role": "user", "content": "What are your pricing plans?"}
    ]
  }'

多輪對話

curl -X POST 'https://your-domain.com/api/v1/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000",
    "conversationId": "conv_abc123",
    "messages": [
      {"role": "user", "content": "What are your pricing plans?"},
      {"role": "assistant", "content": "We offer three plans..."},
      {"role": "user", "content": "Tell me more about the Pro plan"}
    ]
  }'

串流回應

curl -X POST 'https://your-domain.com/api/v1/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

錯誤回應

狀態碼訊息原因
400Invalid JSON bodyJSON 格式錯誤
400Invalid request body欄位缺少或無效
401Missing or invalid Authorization header未提供標頭或格式錯誤
401Invalid API key金鑰無法辨識
403API access requires a Hobby plan or above with active billing方案或帳單狀態不允許使用 API
403Chatbot does not belong to this account代理程式屬於其他帳戶
404Chatbot not found代理程式 ID 無效
429Rate limit exceeded請求次數過多

錯誤回應格式

{
  "message": "Invalid request body",
  "details": {
    "chatbotId": ["Required"]
  }
}

程式碼範例

Node.js

async function sendMessage(chatbotId, message) {
  const response = await fetch('https://your-domain.com/api/v1/chat', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.AGENTKIT_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      chatbotId,
      messages: [{ role: 'user', content: message }],
    }),
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  const data = await response.json();
  return data.text;
}

Python

import requests

def send_message(chatbot_id: str, message: str) -> str:
    response = requests.post(
        'https://your-domain.com/api/v1/chat',
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json',
        },
        json={
            'chatbotId': chatbot_id,
            'messages': [{'role': 'user', 'content': message}],
        },
    )
    response.raise_for_status()
    return response.json()['text']

Node.js（含串流）

async function streamMessage(chatbotId, message) {
  const response = await fetch('https://your-domain.com/api/v1/chat', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.AGENTKIT_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      chatbotId,
      messages: [{ role: 'user', content: message }],
      stream: true,
    }),
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const text = decoder.decode(value);
    process.stdout.write(text); // Print as it streams
  }
}

對話管理

開始新對話

省略 conversationId 即可開始新對話。回應標頭 X-Conversation-ID 會回傳新的 ID。

延續對話

帶上 conversationId 以及所有先前的訊息，即可維持對話脈絡。

訊息紀錄

你必須在每個請求中附上先前的訊息。此 API 是無狀態的——伺服器不會在請求之間保存對話紀錄。

後續步驟