安裝指南

本指南涵蓋 Imbrace SDK 整合所需的一切 — 從安裝、憑證配置、環境設定到服務 URL 覆蓋。

---

系統要求

要求	最低版本
Node.js	18.0.0+
npm	8.0.0+
Python	3.9+
pip	23.0+

---

安裝

TypeScript

從 npm 安裝：

npm install @imbrace/sdk
# 或
yarn add @imbrace/sdk
# 或
pnpm add @imbrace/sdk

Monorepo / 本地開發：

# 步驟 1 — 安裝依賴並建置
cd ts
npm install
npm run build

# 步驟 2（可選）— 全域連結以在其他專案中使用
npm link

在外部專案中：

npm link @imbrace/sdk

驗證：

import { ImbraceClient } from '@imbrace/sdk'
console.log('SDK loaded:', typeof ImbraceClient) // 'function'

Python

從 PyPI 安裝：

pip install imbrace
# 或
uv add imbrace

Monorepo / 本地開發（可編輯模式）：

cd py
pip install -e ".[dev]"

[dev] 旗標額外安裝：pytest, pytest-asyncio, pytest-httpx, ruff, mypy。

驗證：

from imbrace import ImbraceClient
print("SDK loaded:", ImbraceClient)

---

配置憑證

建立 .env 檔案

SDK 不會自動讀取環境變數 — 需要直接將憑證傳入建構子。.env 檔案是使用者慣例；使用 dotenv 或框架的環境載入器讀取。

# 憑證
IMBRACE_API_KEY=your_api_key_here
IMBRACE_ACCESS_TOKEN=your_jwt_token_here

# 組織 ID — 隨每個請求發送
IMBRACE_ORGANIZATION_ID=your_org_id_here

# 可選：直接覆蓋閘道 URL
IMBRACE_BASE_URL=https://app-gatewayv2.imbrace.co

取得 API Key

方式一 — Imbrace Portal： 登入並前往 Settings → API Keys。

方式二 — 透過 API（需要現有 access token）：

curl -X POST https://app-gatewayv2.imbrace.co/private/backend/v1/third_party_token \
  -H "x-access-token: <your_existing_token>" \
  -H "Content-Type: application/json" \
  -d '{"expirationDays": 30}'

所需值為 response.apiKey.apiKey。

---

環境

名稱	閘道 URL	使用場景
develop	https://app-gateway.dev.imbrace.co	內部開發
sandbox	https://app-gateway.sandbox.imbrace.co	整合測試
stable	https://app-gatewayv2.imbrace.co	生產（預設）

透過建構子的 env 選項切換環境，或使用 baseUrl 直接覆蓋 URL：

TypeScript

const client = new ImbraceClient({ env: 'sandbox' })

Python

client = ImbraceClient(env="sandbox")

---

初始化客戶端

TypeScript

import { ImbraceClient } from '@imbrace/sdk'

// 伺服器端 — API Key
const client = new ImbraceClient({
  apiKey:         process.env.IMBRACE_API_KEY,
  organizationId: process.env.IMBRACE_ORGANIZATION_ID,
  baseUrl:        'https://app-gatewayv2.imbrace.co', // 或使用 env: 'stable'
})

// 客戶端 — Access Token（例如 OTP 登入後）
const client = new ImbraceClient({
  accessToken: process.env.IMBRACE_ACCESS_TOKEN,
  baseUrl:     'https://app-gatewayv2.imbrace.co',
})

// OTP 登入流程
const anon = new ImbraceClient({ baseUrl: 'https://app-gatewayv2.imbrace.co' })
await anon.requestOtp('user@example.com')
await anon.loginWithOtp('user@example.com', '123456')
// 令牌自動儲存在客戶端

Python (sync)

import os
from imbrace import ImbraceClient

# 伺服器端 — API Key
client = ImbraceClient(
    api_key=os.environ["IMBRACE_API_KEY"],
    organization_id=os.environ.get("IMBRACE_ORGANIZATION_ID"),
    env="stable",
)

# 客戶端 — Access Token
client = ImbraceClient(
    access_token="eyJhbGci...",
    organization_id="org_xxx",
)

# OTP 登入流程
anon = ImbraceClient(env="stable")
anon.request_otp("user@example.com")
anon.login_with_otp("user@example.com", "123456")

Python (async)

from imbrace import AsyncImbraceClient

async def main():
    async with AsyncImbraceClient(api_key="sk-...") as client:
        me = await client.platform.get_me()
        print(me)

---

快速使用範例

TypeScript

import { ImbraceClient } from '@imbrace/sdk'

const client = new ImbraceClient({ apiKey: process.env.IMBRACE_API_KEY })

// 取得當前使用者資訊
const me = await client.platform.getMe()

// 頻道列表
const channels = await client.channel.listChannels()

// 發送訊息
await client.channel.sendMessage('conv_123', { content: '你好！', type: 'text' })

// AI 補全
const result = await client.ai.complete({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: '總結這份報告。' }],
})

// AI 串流輸出
for await (const chunk of client.ai.stream({ model: 'gpt-4o', messages: [...] })) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '')
}

// AI Agent — 串流對話
const response = await client.aiAgent.streamChat({
  id: 'chat_id',
  assistant_id: 'asst_abc',
  organization_id: 'org_abc',
  messages: [{ role: 'user', content: '你好' }],
})

Python

from imbrace import ImbraceClient

with ImbraceClient(api_key="sk-...") as client:
    # 取得使用者資訊
    me = client.platform.get_me()

    # 頻道和看板列表
    channels = client.channel.list_channels()
    boards   = client.boards.list()
    items    = client.boards.get_items(boards[0]["id"])

    # AI 補全
    result = client.ai.complete(
        model="gpt-4o",
        messages=[{"role": "user", "content": "你好"}],
    )

    # AI Agent — 串流對話
    response = client.ai_agent.stream_chat({
        "id": "chat_id",
        "assistant_id": "asst_abc",
        "organization_id": "org_abc",
        "messages": [{"role": "user", "content": "你好"}],
    })
    for line in response.iter_lines():
        print(line)

---

覆蓋服務 URL

當某個微服務運行在不同位址時使用（例如本地開發、獨立 staging）。

TypeScript

const client = new ImbraceClient({
  env: 'develop',
  services: {
    aiAgent:        'http://localhost:4000/ai-agent',
    dataBoard:      'http://localhost:3001/data-board',
    channelService: 'http://localhost:3002/channel-service',
  },
})

Python

client = ImbraceClient(
    env="develop",
    services={
        "ai_agent":        "http://localhost:4000/ai-agent",
        "data_board":      "http://localhost:3001/data-board",
        "channel_service": "http://localhost:3002/channel-service",
    },
)

所有有效的服務鍵：

Python 鍵	TypeScript 鍵	服務
gateway	gateway	App Gateway
platform	platform	Platform service
channel_service	channelService	Channel service
data_board	dataBoard	Data Board
backend	backend	Board/Items backend (/v1/backend)
ips	ips	IPS service
ai	ai	AI service
marketplaces	marketplaces	Marketplace service
file_service	fileService	File service
message_suggestion	messageSuggestion	Message Suggestion service
predict	predict	Predict service
activepieces	activepieces	ActivePieces
ai_agent	aiAgent	AI Agent service

---

常見錯誤排查

Cannot find package '@imbrace/sdk'

套件未連結。從 ts 重新執行：

npm link
cd /path/to/your-project && npm link @imbrace/sdk

ERR_MODULE_NOT_FOUND（dist/ 中的檔案）

套件尚未建置：

cd ts && npm run build

ModuleNotFoundError: No module named 'imbrace'

cd py && pip install -e ".[dev]"

401 Unauthorized

API Key 已過期或無效。生成新金鑰：

curl -X POST https://app-gatewayv2.imbrace.co/private/backend/v1/third_party_token \
  -H "x-access-token: <your_existing_token>" \
  -H "Content-Type: application/json" \
  -d '{"expirationDays": 30}'

UserWarning: ImbraceClient: no credentials provided

未傳入 api_key 或 access_token。若是刻意為之（例如僅用於登入），可忽略此警告。否則請檢查 .env 檔案。