EntrarComeçar teste grátis
easyCoexistence APIs oficiais

Dê ao agente do OpenAI Agents SDK ferramentas para Instagram, TikTok e WhatsApp

Um agente do OpenAI Agents SDK recebe Instagram, TikTok, WhatsApp e outros canais como ferramentas por meio de MCPServerStreamableHttp apontado para https://easycoexistence.com/api/mcp, com o OAuthClientProvider do MCP Python SDK como handler de autenticação. Um filtro de ferramentas reduz as 35+ ferramentas ao que a tarefa exige, require_approval mantém a publicação em espera até que uma pessoa aprove, e cada chamada chega à rede pela API oficial da plataforma.

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 de versões do pacote mcp do qual o Agents SDK depende, cobrindo as duas versões principais do MCP Python SDK.

interruptions

Onde uma execução pausada lista as chamadas de ferramenta aguardando 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 precisa receber seu token OAuth em authorization; a OpenAI não armazena 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 um agente do Agents SDK se conecta ao easyCoexistence?

Por meio do MCPServerStreamableHttp, com o OAuthClientProvider do MCP Python SDK em params["auth"]. O Agents SDK passa esse handler ao cliente HTTP que constrói, então o provider descobre o servidor de autorização do easyCoexistence, registra seu agente como cliente público, faz um único login no navegador com PKCE e renova os tokens de acesso de uma hora com o refresh token. O exemplo usa o MCP Python SDK v2, em que o handler precisa ser um httpx2.Auth, e é isso que o provider é. Um objeto de armazenamento mantém o registro e os tokens entre execuções; o arquivo abaixo substitui um cofre de segredos. create_static_tool_filter lista as ferramentas que o agente pode ver, e require_approval nomeia 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 nomeada ser executada. A execução então volta com interruptions em vez de uma resposta final: transforme o resultado em um 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 única chamada, então o agente não consegue reutilizar uma aprovação para uma segunda publicação. O servidor permanece aberto durante a pausa porque o loop roda dentro do bloco async with. Para uma revisão que leva horas, o SDK pode armazenar o estado como JSON e carregá-lo depois 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 um comentário no TikTok ou uma DM no Instagram inicia uma execução?

Por meio da sua própria rota HTTPS, já 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; contas do TikTok encaminham comentários. A rota verifica X-EC-Signature, um HMAC-SHA256 do timestamp, um ponto e o corpo bruto, responde dentro dos 8 segundos do easyCoexistence e enfileira o evento. Um worker então chama Runner.run com o evento como entrada. Nas DMs, uma sessão indexada pela conta e pelo remetente mantém a conversa; um comentário do TikTok precisa apenas do comentário e do vídeo, então pode rodar sem sessão.

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 resposta, e muitas respostas quase idênticas em pouco tempo podem ser ocultadas como spam.
  • DMs do Instagram: respostas apenas a pessoas que escreveram nas últimas 24 horas, em no máximo 1.000 bytes de texto UTF-8.
  • WhatsApp: send_message em até 24 horas da última mensagem do cliente, e send_template com um template aprovado depois disso.
  • Agendamento: scheduled_at aceita ISO 8601 com fuso horário, de 1 minuto a 90 dias à frente, e list_scheduled_posts mostra a fila.

O agente pode usar HostedMCPTool ou rodar sem login?

Os dois, cada um com seus prós e contras. O HostedMCPTool entrega o servidor à Responses API, cuja ferramenta MCP recebe um token de acesso OAuth em authorization e precisa dele em cada requisição, já que a OpenAI não o armazena; um token de acesso do easyCoexistence dura uma hora, então seu código o renova antes de cada execução. Para uma tarefa sem ninguém para fazer login, dispense o MCP: ferramentas de função que chamam a Partner API com uma chave ec_live_ podem enfileirar publicações por POST /api/v1/channels/:id/posts e buscar tokens do TikTok, YouTube e LinkedIn atualizados em GET /api/v1/channels/:id?credentials=1, enquanto regras de comentário e automações respondem no easyCoexistence sem nenhum agente rodando.

Erros comuns

  • Manter o client_session_timeout_seconds de 5 segundos para publicar. Uma publicação espera a API da rede, então uma chamada lenta pode dar timeout no agente depois que o easyCoexistence já tiver encaminhado a publicação; dê um minuto e verifique list_scheduled_posts antes de repetir a chamada.
  • Passar external_id como account_id. As ferramentas recebem account_id, o ID do easyCoexistence para a conta; external_id é o ID próprio da conta no Instagram, TikTok ou Facebook.
  • Aprovar interruptions em loop sem uma pessoa no meio. require_approval só protege a publicação quando um humano, ou uma regra em que você confia, decide sobre cada chamada pendente.
  • Alimentar o agente com a própria atividade da conta. O Instagram devolve as DMs da conta como echoes, com is_echo true, e as respostas públicas dela como novos comentários; filtre os dois antes de Runner.run.
Fazendo isso com o EasyCoexistence

O easyCoexistence dá aos seus agentes do OpenAI Agents SDK alcance até os clientes no WhatsApp, Instagram, Facebook, TikTok, YouTube, LinkedIn e outros canais, cada um pela sua API oficial: um servidor MCP que faz login com OAuth, eventos assinados para comentários e DMs e uma Partner API para tarefas que rodam sem supervisão, com cada conexão monitorada 24/7. De US$ 9 a US$ 0.75 por conexão por mês, com o preço caindo conforme você adiciona conexões, e os primeiros 3 dias grátis.

O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.

Perguntas frequentes

O agente precisa de uma chave de API do easyCoexistence?

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

O mesmo agente pode responder 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 como receber as mensagens.

Qual modelo o agente usa?

O que você definir no Agent. As ferramentas MCP funcionam igual qualquer que seja o modelo que o SDK usa, o uso do modelo é cobrado pelo provedor dele, e o easyCoexistence cobra por conexão.

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

De US$ 9 a US$ 0.75 por conexão por mês, com o preço caindo conforme você adiciona conexões, igual em cada rede. O servidor MCP, os eventos encaminhados e a Partner API estão incluídos, e os primeiros 3 dias são grátis.

Continue lendo

Conecte seu primeiro canal em dois minutos.

Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.

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

Verificado em