Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

Dar a um agente do OpenAI Agents SDK ferramentas para Instagram, TikTok e WhatsApp

Um agente do OpenAI Agents SDK recebe o Instagram, TikTok, WhatsApp e outros canais como ferramentas através de MCPServerStreamableHttp apontado para https://easycoexistence.com/api/mcp, com o OAuthClientProvider do MCP Python SDK como gestor de autenticação. Um filtro de ferramentas reduz as 35+ ferramentas à tarefa em causa, require_approval retém a publicação até uma pessoa a aprovar, e cada chamada chega à rede através da respetiva API oficial.

httpx2.Auth

O que o MCPServerStreamableHttp recebe em params["auth"] com o MCP Python SDK v2; com a v1 recebe um httpx.Auth.

mcp>=1.19.0,<3

O intervalo da versão do pacote mcp de que o Agents SDK depende, abrangendo as duas versões principais do MCP Python SDK.

interruptions

Onde uma execução pausada lista as chamadas de ferramentas à espera de aprovação, que um RunState aprova ou rejeita antes de o Runner.run retomar.

Per request

Com que frequência a ferramenta MCP da Responses API tem de receber o token OAuth em authorization; a OpenAI não guarda o valor.

40 a minute

Chamadas que o TikTok permite por conta autorizada em cada endpoint da Accounts API, incluindo as respostas a comentários.

Como é que um agente do Agents SDK se liga à easyCoexistence?

Através de MCPServerStreamableHttp, com o OAuthClientProvider do MCP Python SDK em params["auth"]. O Agents SDK passa esse gestor ao cliente HTTP que constrói, pelo que o próprio provider descobre o servidor de autorização da easyCoexistence, regista o agente como cliente público, executa um único início de sessão no navegador com PKCE e renova os tokens de acesso, de uma hora, com o token de atualização. O exemplo usa o MCP Python SDK v2, em que o gestor tem de ser um httpx2.Auth, que é o que o provider é. Um objeto de armazenamento guarda o registo e os tokens entre execuções; o ficheiro abaixo substitui um cofre de segredos. create_static_tool_filter lista as ferramentas que o agente pode ver, e require_approval indica as que aguardam uma pessoa.

The MCP server, signed in over OAuth, with a filter and approvals
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}},
    )

Como manter a publicação atrás da aprovação de uma pessoa?

Com require_approval no servidor, que pausa a execução antes de uma ferramenta indicada ser executada. A execução devolve então interruptions em vez de uma resposta final: transforme o resultado num RunState, aprove ou rejeite cada chamada pendente e chame Runner.run de novo com o mesmo agente e o estado. Com always_approve deixado em False, cada sim cobre uma só chamada, pelo que o agente não pode reutilizar uma aprovação para uma segunda publicação. O servidor mantém-se aberto durante a pausa porque o ciclo corre dentro do bloco async with. Para uma revisão que demore horas, o SDK pode guardar o estado em JSON e carregá-lo mais tarde com RunState.from_json.

Run the agent and resume it after each decision
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_output

Como é que um comentário no TikTok ou uma DM no Instagram inicia uma execução?

Através de uma rota HTTPS própria, uma vez que o agente só ouve o que pede ao servidor MCP. set_social_webhook_destination aponta os comentários, menções e DMs de uma conta para a rota e devolve um segredo de assinatura uma única vez; as contas do TikTok encaminham comentários. A rota verifica X-EC-Signature, um HMAC-SHA256 do carimbo de data/hora, um ponto e o corpo bruto, responde dentro do limite de 8 segundos da easyCoexistence e põe o evento em fila. Um processo em segundo plano chama depois Runner.run com o evento como entrada. Para as DMs, uma sessão identificada pela conta e pelo remetente mantém a conversa; um comentário no TikTok precisa apenas do comentário e do seu vídeo, pelo que pode correr sem um.

O que as instruções do agente devem dizer sobre cada rede?

As regras que a API de cada rede aplica à conta, escritas onde o modelo as lê:

  • TikTok: reply_to_comment publica em público e precisa do ID do vídeo como post_id; send_social_dm recusa contas do TikTok.
  • Volume no TikTok: até 40 chamadas por minuto por conta no endpoint de respostas, e muitas respostas quase idênticas num curto espaço de tempo podem ser ocultadas como spam.
  • DMs do Instagram: só se responde a quem escreveu nas últimas 24 horas, com um máximo de 1,000 bytes de texto UTF-8.
  • WhatsApp: send_message dentro de 24 horas da última mensagem do cliente, e send_template com um template aprovado fora desse prazo.
  • Agendamento: scheduled_at aceita ISO 8601 com fuso horário, de 1 minuto a 90 dias à frente, e list_scheduled_posts mostra a fila.

Pode o agente usar HostedMCPTool, ou correr sem início de sessão?

Ambas as opções, com compromissos. O HostedMCPTool entrega o servidor à Responses API, cuja ferramenta MCP recebe um token de acesso OAuth em authorization e precisa dele em cada pedido, uma vez que a OpenAI não o guarda; um token de acesso da easyCoexistence dura uma hora, pelo que o código o renova antes de cada execução. Para uma tarefa sem ninguém para iniciar sessão, prescinde-se do MCP: as ferramentas de função que chamam a Partner API com uma chave ec_live_ podem colocar publicações em fila através de POST /api/v1/channels/:id/posts e obter tokens atualizados do TikTok, do YouTube e do LinkedIn através de GET /api/v1/channels/:id?credentials=1, enquanto as regras de comentários e as automações respondem na easyCoexistence sem nenhum agente em execução.

Erros comuns

  • Manter o client_session_timeout_seconds de 5 segundos para a publicação. Uma publicação aguarda a API da rede, pelo que uma chamada lenta pode expirar no agente depois de a easyCoexistence já ter enviado a publicação; defina um minuto e verifique list_scheduled_posts antes de voltar a tentar.
  • Passar external_id como account_id. As ferramentas recebem account_id, o ID da conta na easyCoexistence; external_id é o ID próprio da conta no Instagram, TikTok ou Facebook.
  • Aprovar interrupções em ciclo sem nenhuma pessoa envolvida. require_approval só protege a publicação quando uma pessoa, ou uma regra em que confie, decide sobre cada chamada pendente.
  • Alimentar o agente com a atividade da própria conta. O Instagram devolve as DMs da conta como ecos com is_echo true e as respostas públicas da conta como comentários novos; filtrar ambos antes de Runner.run.
Fazer isto com a EasyCoexistence

A easyCoexistence dá aos agentes do OpenAI Agents SDK alcance a clientes no WhatsApp, Instagram, Facebook, TikTok, YouTube, LinkedIn e mais canais, cada um através da respetiva API oficial: um servidor MCP que inicia sessão com OAuth, eventos assinados para comentários e DMs, e uma Partner API para tarefas que correm sem supervisão, com cada ligação monitorizada 24/7. De US$ 9 a US$ 0.75 por ligação por mês, descendo à medida que adiciona ligações, com os primeiros 3 dias gratuitos.

Perguntas frequentes

O agente precisa de uma chave de API da easyCoexistence?

Não para o MCP. O início de sessão OAuth emite ao agente os próprios tokens; uma chave ec_live_ do painel só serve para o código que chama a Partner API em vez do servidor MCP.

O mesmo agente pode responder a mensagens do WhatsApp?

Sim, com as ferramentas do número: list_numbers para o connection_id, send_message dentro de 24 horas da última mensagem do cliente e send_template fora desse prazo. O guia do OpenAI Agents SDK para WhatsApp explica a receção das mensagens.

Que modelo usa o agente?

O que indicar no Agent. As ferramentas MCP funcionam da mesma forma qualquer que seja o modelo que o SDK executa, a utilização do modelo é faturada pelo respetivo fornecedor, e a easyCoexistence cobra por ligação.

Quanto custa a easyCoexistence para um agente do OpenAI Agents SDK?

De US$ 9 a US$ 0.75 por ligação por mês, descendo à medida que adiciona ligações, o mesmo em cada rede. O servidor MCP, os eventos encaminhados e a Partner API estão incluídos, e os primeiros 3 dias são gratuitos.

Continue a ler

Ligue o seu primeiro canal em dois minutos.

Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.

  • 3 dias grátis
  • Cancele quando quiser
  • Só APIs oficiais
  • Monitorizado 24/7

Verificado em