OpenAI Agents SDK -agentti WhatsAppiin

Miten WhatsApp-viestistä tulee agentin ajo?

Oman sovelluksesi reitin kautta, jota Meta kutsuu. Aseta numeron webhookin kohteeksi tämä reitti ja lisää polkuun pitkä satunnainen salaisuus. Reitti vastaa Metan vahvistus-GET-pyyntöön palauttamalla hub.challenge pelkkänä tekstinä, hyväksyy jokaisen POST-pyynnön, vastaa heti 200 ja jonottaa työn, koska Meta yrittää hitaita vastauksia uudelleen ja agentti ajettaisiin kahdesti.

Työprosessi lukee sitten lähettäjän ja tekstin payloadista ja kutsuu Runner.run. Anna istunto, jonka tunnus on lähettäjän numero: SDK tallentaa keskustelun sen tunnuksen alle, joten saman asiakkaan seuraava viesti jatkaa siitä, mihin edellinen jäi, eikä kaksi asiakasta koskaan jaa historiaa. SQLiteSession riittää alkuun, ja usealle työprosessille SDK:ssa on myös Redis- ja SQLAlchemy-istunnot.

URL:n salaisuus on tässä todennus. Meta allekirjoittaa toimitukset Tech Providerin sovelluksen salaisuudella, joten asiakas ei voi vahvistaa allekirjoitusotsaketta.

import os, httpx
from agents import Agent, Runner, SQLiteSession

agent = Agent(name="Front desk", instructions="Answer briefly and politely.")
URL = f"https://graph.facebook.com/v25.0/{os.environ['PHONE_NUMBER_ID']}/messages"

async def handle(sender: str, text: str) -> None:
    session = SQLiteSession(sender, "whatsapp.db")
    result = await Runner.run(agent, text, session=session)
    async with httpx.AsyncClient() as http:
        await http.post(
            URL,
            headers={"Authorization": f"Bearer {os.environ['WA_TOKEN']}"},
            json={"messaging_product": "whatsapp", "to": sender,
                  "type": "text", "text": {"body": result.final_output}},
        )

Miksi vastauksen pitää lähteä koodistasi eikä agentilta?

Koska ainoa sääntö, jota ei saa rikkoa, on aikasääntö, ja koodi valvoo sitä paremmin kuin kehote. Meta avaa 24 tunnin asiakaspalveluikkunan, kun asiakas kirjoittaa. Sen sisällä vapaa teksti menee läpi. Ikkunan ulkopuolella vain hyväksytty viestipohja kelpaa, ja vapaa teksti palaa virheellä 131047.

Työprosessi, joka vastaa juuri saapuneeseen viestiin, on aina ikkunan sisällä, joten result.final_output tekstinä lähettäminen on turvallista jo rakenteen puolesta. Myöhemmin tehtävä työ, kuten seuraavan aamun seuranta tai muistutus, kannattaa ohjata erilliselle polulle, joka lähettää viestipohjan eikä koskaan vapaata tekstiä.

Agentilla voi silti olla työkaluja. Anna sille funktiotyökalut tietojen hakuun, esimerkiksi tilaukselle tai varaukselle, ja pidä WhatsApp-lähetys työprosessissa. Samalla access token pysyy poissa kaikesta, mitä malli voi kutsua mielivaltaisilla argumenteilla.

Voiko agentti käyttää EasyCoexistencen MCP-palvelinta?

Voi, MCPServerStreamableHttp:n kautta, mutta asetukset vaativat otsaketta enemmän. SDK hyväksyy joko Authorization-otsakkeen tai httpx.Auth-olion kohdassa params["auth"]. EasyCoexistencen MCP-palvelin myöntää omat OAuth-tokenit selaimessa tehdyn kirjautumisen jälkeen, dynaamisella asiakasrekisteröinnillä ja PKCE:llä, joten pysyvää avainta ei ole. MCP:n Python-SDK sisältää OAuthClientProviderin, HTTP-todennuskäsittelijän, joka suorittaa tämän kulun PKCE:llä ja tokenin uusinnalla, ja se sijoitetaan kohtaan params["auth"].

Se kannattaa, kun agentin halutaan päättävän itse: tarkistaa numeron tila, lukea viestipohjan tila tai valita send_message ja send_template välillä työkalukuvausten sääntöjen mukaan. Pelkästään vastaavalle vastaanotolle yllä oleva työprosessi on lyhyempi ja siinä on vähemmän mikä voi mennä pieleen.

Webhook pysyy kummassakin tapauksessa. MCP toimii pyyntö–vastaus-periaatteella, ja asiakkaan viesti voi tavoittaa agentin vain reitin kautta, jota Meta kutsuu.

Yleiset virheet

• Agentin ajaminen ennen kuin Metalle palautetaan 200. Hidas vastaus yritetään uudelleen, ja asiakas saa kaksi vastausta.
• Yhden istunnon käyttö kaikille asiakkaille. Sido istunto lähettäjän numeroon, muuten historiat sekoittuvat.
• Viivästetyn seurantaviestin lähettäminen vapaana tekstinä. 24 tunnin jälkeen se epäonnistuu virheellä 131047; lähetä viestipohja.

Usein kysytyt kysymykset

Lue lisää