SDK de Python | SignalCore

signalcore es la API en Python: cada endpoint de la referencia es un método, con sus tipos. Para tu servidor, con una clave secreta; nunca en una página.

pip install "signalcore>=2"

Python 3.10 o posterior. La versión 2 es la de SignalCore 2.0.

Hablar con un agente

from signalcore import SignalCore
client = SignalCore("sk_...")  # o la variable SIGNALCORE_API_KEY
equipo = client.squads.list()[0]
agente = client.agents.create(equipo["id"], name="Recepción", instructions="Responde breve.")
conversacion = client.conversations.start(agente["id"])
respuesta = client.conversations.say(conversacion["id"], text="¿Abrís el sábado?", wait=True)
print(respuesta["status"], respuesta["replies"][0]["text"])

Con wait=True la respuesta llega cuando el agente termina (hasta un minuto). status es done, waiting (espera una respuesta o un sí, en waiting) o failed (con error).

Organizaciones de tus clientes

cliente = client.orgs.create(name="Clínica Norte")
suyo = SignalCore("sk_...", org=cliente["id"])  # cada llamada lleva SignalCore-Org

Tokens de persona

Tu servidor crea el token y tu página lo usa con los componentes:

token = client.tokens.create(agents=[agente["id"]], external_id="user_42", name="Lucía Pérez")

En directo

Lo que pasa en la conversación, mensaje a mensaje, como un iterador asíncrono:

from signalcore import AsyncSignalCore
async with AsyncSignalCore("sk_...") as client:
    async with client.conversations.live(conversacion_id) as live:
        await live.say("Hola")
        async for frame in live:
            if frame["type"] == "done":
                break

AsyncSignalCore tiene los mismos métodos que SignalCore, con await.

Webhooks

verify comprueba la firma sobre el cuerpo tal como llega y te da el evento:

from signalcore import SignatureError, verify
@app.post("/signalcore")
async def webhook(request: Request):
    try:
        evento = verify(await request.body(), request.headers, WEBHOOK_SECRET)
    except SignatureError:
        raise HTTPException(400)

Errores

Todo lo que la API rechaza es un ApiError con status, code (para tu código) y detail (en palabras), los mismos de la API.

from signalcore import ApiError
try:
    client.agents.get("agt_...")
except ApiError as error:
    if error.code == "not_found":
        ...

Cada endpoint

El método se llama como la operación de la referencia: agents_get es client.agents.get(...). Los parámetros de la ruta van primero; el cuerpo y la consulta, con nombre. Las escrituras aceptan idempotency_key=, y las listas largas se recorren con iter (client.runs.iter(...)).