> This page is for Inicio.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://signalcore.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://signalcore.ai/docs/_mcp/server.

# SDK de Python

`signalcore` es la [API](/guias/api) en Python: cada endpoint de la [referencia](/referencia) es un
método, con sus tipos. Para tu servidor, con una clave secreta; nunca en una página.

```bash
pip install "signalcore>=2"
```

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

## Hablar con un agente

```python
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

```python
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](/guias/componentes):

```python
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:

```python
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:

```python
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](/guias/api#errores).

```python
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(...)`).