SDK

Python

El paquete oficial inceptiva requiere Python 3.10 o posterior y no tiene dependencias de ejecución.

Instalación

shell

pip install inceptiva

Cliente y agente

python

import os
from inceptiva import Inceptiva

client = Inceptiva(
    api_key=os.environ["INCEPTIVA_API_KEY"],
    agent_id=os.environ["INCEPTIVA_AGENT_ID"],
)

agent = client.get_agent()
print(agent.name, agent.capabilities)

Respuestas y continuidad

python

first = client.responses.create(
    message="Analiza esta oportunidad",
    metadata={"source": "crm"},
)

follow_up = client.responses.create(
    message="¿Cuál es el siguiente paso?",
    conversation_id=first.conversation_id,
)

print(follow_up.response)
print(follow_up.citations)

client.invoke(...) permanece disponible como alias compatible.

Streaming SSE

python

from inceptiva import ResponseOutputTextDelta, collect_stream

events = client.responses.stream(
    message="Resume la oportunidad",
    conversation_id=follow_up.conversation_id,
)

for event in events:
    if isinstance(event, ResponseOutputTextDelta):
        print(event.delta, end="", flush=True)

Puedes cerrar anticipadamente el generador con events.close(). collect_stream(events) acumula los deltas y devuelve un InvokeResponse final. Un stream iniciado nunca se reintenta automáticamente.

Historial y eliminación

python

history = client.conversations.get_messages(follow_up.conversation_id)

for message in history.items:
    print(message.role, message.content, message.citations)

client.conversations.delete(follow_up.conversation_id)

Errores y Retry-After

python

from inceptiva import InceptivaApiError, InceptivaRateLimitError

try:
    client.get_agent()
except InceptivaRateLimitError as error:
    print(error.retry_after)
except InceptivaApiError as error:
    print(error.status, error.detail)

También se exportan errores específicos para 401, 403, 404 y 422. Cada operación acepta un timeout opcional. El SDK solo expone citas públicas y nunca retrieval_sources.

Contrato robusto 0.4.0

python

result = client.responses.create(
    message="Actualiza el resumen",
    external_reference="ticket-4821",
    idempotency_key="request-unique-id",
    metadata={"customer_id": "123", "source": "helpcenter"},
)

history = client.conversations.get_messages(result.conversation_id, page=1, page_size=50)
print(result.response_metadata.idempotency_replayed)
print(history.total, history.has_more)