為 OpenAI Agents SDK 代理加上 Instagram、TikTok 和 WhatsApp 工具
OpenAI Agents SDK 代理可透過 MCPServerStreamableHttp 指向 https://easycoexistence.com/api/mcp,並以 MCP Python SDK 的 OAuthClientProvider 作為認證處理器,將 Instagram、TikTok、WhatsApp 及更多渠道以工具形式提供給代理。工具篩選器可把 35 多個工具縮減至所需範圍,require_approval 讓發佈動作等待人員批准,每次呼叫則經由各平台的官方 API 送達。
MCP Python SDK v2 下,MCPServerStreamableHttp 於 params["auth"] 所接收的內容;v1 則接收 httpx.Auth。
Agents SDK 所依賴的 mcp 套件版本範圍,涵蓋 MCP Python SDK 的兩個主要版本。
暫停的執行會列出等待批准的工具呼叫,RunState 可於 Runner.run 恢復前批准或拒絕。
Responses API 的 MCP 工具須多久於 authorization 中傳送一次 OAuth 權杖;OpenAI 不會儲存該值。
TikTok 在每個 Accounts API 端點上,每個已授權帳戶允許的呼叫次數(包括留言回覆)。
Agents SDK 代理如何連接 easyCoexistence?
透過 MCPServerStreamableHttp,並在 params["auth"] 中傳入 MCP Python SDK 的 OAuthClientProvider。Agents SDK 會把該處理器交給它所建立的 HTTP 客戶端,因此提供者會探索 easyCoexistence 的授權伺服器、將你的代理註冊為公開客戶端、以 PKCE 完成一次瀏覽器登入,並以更新權杖重新整理有效期為一小時的存取權杖。範例使用 MCP Python SDK v2,其中處理器須為 httpx2.Auth,而提供者本身即屬此類。儲存物件會在多次執行之間保存註冊資料與權杖,下方的檔案則代替機密儲存。create_static_tool_filter 列出代理可見的工具,require_approval 則指定需等待人員批准的工具。
import json, webbrowser
from pathlib import Path
from urllib.parse import parse_qs, urlparse
from pydantic import AnyUrl
from mcp.client.auth import AuthorizationCodeResult, OAuthClientProvider
from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
from agents.mcp import MCPServerStreamableHttp, create_static_tool_filter
URL = "https://easycoexistence.com/api/mcp"
SAVED = Path("easycoexistence-oauth.json") # a secret store in production
class SavedSignIn: # the MCP SDK's TokenStorage: registration and tokens survive restarts
def _read(self) -> dict:
return json.loads(SAVED.read_text()) if SAVED.exists() else {}
def _write(self, key: str, model) -> None:
data = self._read()
data[key] = model.model_dump(mode="json")
SAVED.write_text(json.dumps(data))
async def get_tokens(self):
t = self._read().get("tokens")
return OAuthToken(**t) if t else None
async def set_tokens(self, tokens): self._write("tokens", tokens)
async def get_client_info(self):
c = self._read().get("client")
return OAuthClientInformationFull(**c) if c else None
async def set_client_info(self, info): self._write("client", info)
async def open_sign_in(url: str) -> None:
webbrowser.open(url)
async def code_from_redirect() -> AuthorizationCodeResult:
q = parse_qs(urlparse(input("Address after sign-in: ")).query)
return AuthorizationCodeResult(code=q["code"][0], state=q["state"][0])
oauth = OAuthClientProvider(
server_url=URL,
client_metadata=OAuthClientMetadata(
client_name="Social desk agent", # shown on easyCoexistence's consent screen
redirect_uris=[AnyUrl("http://localhost:3030/callback")],
scope="mcp",
),
storage=SavedSignIn(),
redirect_handler=open_sign_in,
callback_handler=code_from_redirect,
)
PUBLISH = ["publish_instagram_post", "publish_tiktok_post", "publish_facebook_post"]
def easycoexistence() -> MCPServerStreamableHttp:
return MCPServerStreamableHttp(
name="easyCoexistence",
params={"url": URL, "auth": oauth, "timeout": 60},
client_session_timeout_seconds=60, # publishing waits on the network's API
cache_tools_list=True,
tool_filter=create_static_tool_filter(allowed_tool_names=[
"list_social_accounts", "list_social_posts", "list_social_comments",
"reply_to_comment", "list_scheduled_posts", *PUBLISH,
]),
require_approval={"always": {"tool_names": PUBLISH}},
)如何讓發佈動作須經人員批准?
透過伺服器上的 require_approval,在指定工具執行前暫停執行。執行隨後會返回中斷項目,而非最終答案:把結果轉為 RunState,逐一批准或拒絕每個待決呼叫,再以相同的代理與狀態重新呼叫 Runner.run。若 always_approve 保持 False,每次同意只涵蓋一個呼叫,因此代理無法把批准重複用於第二次發佈。由於迴圈在 async with 區塊內執行,暫停期間伺服器仍保持開啟。若審查需時數小時,SDK 可把狀態儲存為 JSON,之後再以 RunState.from_json 載入。
from agents import Agent, Runner
RULES = "You run Acme's social accounts. Schedule posts with scheduled_at; TikTok replies are public."
async def run(task: str) -> str:
async with easycoexistence() as server:
agent = Agent(name="Social desk", instructions=RULES, mcp_servers=[server])
result = await Runner.run(agent, task)
while result.interruptions: # a publish tool is waiting for a decision
state = result.to_state()
for item in result.interruptions:
if await ask_a_person(item): # your review screen, chat message or queue
state.approve(item, always_approve=False)
else:
state.reject(item)
result = await Runner.run(agent, state)
return result.final_outputTikTok 留言或 Instagram 私訊如何啟動執行?
透過你自己的 HTTPS 路由,因為代理只會接收它向 MCP 伺服器請求的內容。set_social_webhook_destination 會把帳戶的留言、提及與私訊指向該路由,並且只回傳一次簽署密鑰;TikTok 帳戶會轉發留言。路由會檢查 X-EC-Signature,即時間戳、句點與原始內容的 HMAC-SHA256,並於 easyCoexistence 規定的 8 秒內回應,然後將事件排入佇列。工作程序隨後以該事件作為輸入呼叫 Runner.run。私訊方面,以帳戶與發送者為鍵的會話可延續對話;TikTok 留言只需留言及其影片,因此可不使用會話而執行。
代理的指示應如何說明各平台?
各平台 API 套用於帳戶的規則,寫於模型讀取之處:
- TikTok:
reply_to_comment會公開回覆,並需以影片的 ID 作為post_id;send_social_dm會拒絕 TikTok 帳戶。 - TikTok 用量:每個帳戶在回覆端點每分鐘最多 40 次呼叫,而短時間內大量近乎相同的回覆可能會被視為垃圾訊息而隱藏。
- Instagram 私訊:只可回覆過去 24 小時內曾發訊的人,且文字不得超過 1,000 位元組(UTF-8)。
- WhatsApp:客戶最後一則訊息後 24 小時內使用
send_message;其後則以已批准的訊息範本透過send_template發送。 - 時間設定:
scheduled_at接受含時區的 ISO 8601 格式,可設於 1 分鐘至 90 天後;list_scheduled_posts會顯示排程佇列。
代理可否使用 HostedMCPTool,或不經登入而運作?
兩者皆可,但各有取捨。HostedMCPTool 會把伺服器交給 Responses API,而其 MCP 工具需要在 authorization 中傳送 OAuth 存取權杖,且由於 OpenAI 不會儲存該權杖,因此每次請求都必須附上。easyCoexistence 存取權杖有效期為一小時,因此你的程式應於每次執行前重新整理。若工作無需人員登入,則可略過 MCP:呼叫 Partner API 的函數工具可使用 ec_live_ 金鑰,透過 POST /api/v1/channels/:id/posts 將貼文加入佇列,並以 GET /api/v1/channels/:id?credentials=1 取得 TikTok、YouTube 及 LinkedIn 最新的權杖;而留言規則與自動化則可在 easyCoexistence 上回覆,無需代理運行。
常見錯誤
- 發佈時仍沿用 5 秒的 client_session_timeout_seconds。發佈需等待各平台的 API,因此緩慢的呼叫可能在 easyCoexistence 已將貼文轉交後,於代理端逾時;應預留一分鐘,並於重試前檢查 list_scheduled_posts。
- 把 external_id 當作 account_id 傳入。工具接受的是 account_id,即 easyCoexistence 為該帳戶分配的 ID;external_id 則是該帳戶在 Instagram、TikTok 或 Facebook 上的平台自身 ID。
- 在沒有人參與的迴圈中批准中斷項目。require_approval 只有在人員,或你信任的規則,對每個待決呼叫作出判斷時,才能保護發佈。
- 把帳戶自身的活動提供給代理。Instagram 會將帳戶的私訊以 is_echo 為 true 的回音返回,並將其公開回覆作為新留言返回;兩者都應在 Runner.run 之前過濾掉。
easyCoexistence 為你的 OpenAI Agents SDK 代理提供觸及 WhatsApp、Instagram、Facebook、TikTok、YouTube、LinkedIn 等渠道客戶的能力,每個渠道皆透過其官方 API 運作:以 OAuth 登入的 MCP 伺服器、留言與私訊的簽署事件,以及適用於無人值守工作的 Partner API,並以 24/7 監控每個連接。每個連接每月 US$ 9 至 US$ 0.75,連接越多越便宜,並提供首 3 天免費試用。
常見問題
OpenAI Agents SDK 代理是否需要 easyCoexistence 的 API 金鑰?
MCP 不需要。OAuth 登入會為代理發出其專屬權杖;控制台取得的 ec_live_ 金鑰只供呼叫 Partner API 而非 MCP 伺服器的程式使用。
同一個代理能否回覆 WhatsApp 訊息?
可以,使用號碼相關的工具:list_numbers 取得 connection_id,客戶最後一則訊息後 24 小時內使用 send_message,之後則使用 send_template。接收訊息的方法請參閱 OpenAI Agents SDK 的 WhatsApp 指南。
代理使用哪個模型?
由你在 Agent 中指定的模型。無論 SDK 運行哪個模型,MCP 工具的運作方式都相同;模型用量由其供應商收費,而 easyCoexistence 按連接收費。
easyCoexistence 對 OpenAI Agents SDK 代理的收費是多少?
每個連接每月 US$ 9 至 US$ 0.75,連接越多越便宜,各平台收費一致。MCP 伺服器、轉發的事件及 Partner API 均包括在內,首 3 天免費。
繼續閱讀
兩分鐘內連接您的第一個頻道。
無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。
- 免費試用 3 天
- 隨時取消
- 只用官方 API
- 24/7 監察
驗證日期