Cortex Agent SDK

SDK async para construir agentes con una API pequeña y control explícito del loop, las tools, el historial y el ciclo de vida.

Cortex Agent SDK está en alfa. La API puede cambiar antes de la versión 0.1.0.

Requisitos

• Python >=3.13.
• Una credencial del provider elegido.

Instalación

Para OpenAI Responses:

uv add "cortex-agent-sdk[openai]"

También puede instalarse con pip:

python -m pip install "cortex-agent-sdk[openai]"

El core instala únicamente Pydantic y JSON Schema. Los providers y transportes se habilitan mediante extras opcionales:

• openai: engine de OpenAI Responses.
• talos: conexión de OpenAI mediante Talos.
• redis: sesiones persistentes en Redis.
• postgres: sesiones persistentes en PostgreSQL.
• all: todas las integraciones disponibles.

Uso mínimo

El SDK oficial de OpenAI lee OPENAI_API_KEY del entorno.

import asyncio

from cortex_agent_sdk import Agent
from cortex_agent_sdk.openai import OpenAIEngine, OpenAIOptions


async def main() -> None:
    options = OpenAIOptions(max_output_tokens=128, reasoning_effort="low")
    async with Agent(OpenAIEngine("gpt-5.6-luna", options=options)) as agent:
        result = await agent.run("Responde únicamente: hola")
    print(result.text)


asyncio.run(main())

Tools

Una función async decorada puede exponerse al modelo como respuesta final:

import asyncio

from cortex_agent_sdk import Agent, final_answer
from cortex_agent_sdk.openai import OpenAIEngine


@final_answer
async def sumar(a: int, b: int) -> str:
    """Suma dos enteros."""
    return str(a + b)


async def main() -> None:
    instructions = "Para sumar, usa siempre la herramienta sumar."
    async with Agent(
        OpenAIEngine("gpt-5.6-luna"),
        instructions=instructions,
        tools=(sumar,),
    ) as agent:
        result = await agent.run("Suma 20 y 22.")
    print(result.text)


asyncio.run(main())

Capacidades del alfa

• Loop async acotado.
• Tools async con schema inferido o explícito.
• Historial y sesiones en memoria, Redis o PostgreSQL.
• Hooks locales.
• Timeouts para providers y tools.
• Respuesta tipada con texto, usage, razón de salida y respuesta raw.
• OpenAI Responses directo o mediante Talos.

Google conserva un namespace estable para la evolución multiproveedor, pero todavía no incluye un engine funcional. Anthropic y streaming están fuera de este alfa.

Sesiones persistentes

Redis y PostgreSQL implementan el mismo contrato de sesiones que el store en memoria. El historial queda aislado por session_id, ligado al provider y modelo originales, y protegido con lease renovable, fencing token y compare-and-swap.

Redis no requiere inicialización de schema:

from cortex_agent_sdk import Agent
from cortex_agent_sdk.openai import OpenAIEngine
from cortex_agent_sdk.redis import RedisSessionStore


store = RedisSessionStore("redis://127.0.0.1:6379/0")
agent = Agent(
    OpenAIEngine("gpt-5.6-luna"),
    session_store=store,
    own_session_store=True,
)
result = await agent.run("Hola", session_id="producto:tenant:usuario")
await agent.aclose()

PostgreSQL exige crear su tabla de forma explícita una vez:

from cortex_agent_sdk.postgres import PostgresSessionStore


store = PostgresSessionStore("postgresql://user:password@localhost/app")
await store.setup()

Una tarea periódica puede ejecutar await store.cleanup_expired() para vaciar historiales vencidos que nunca volvieron a solicitarse. El row mínimo permanece para conservar el fencing counter.

Agent.aclose() hace un cierre ordenado: deja de aceptar turnos nuevos, espera los turnos activos y después cierra los recursos que posee. El límite se configura con AgentOptions.shutdown_timeout_seconds. Si vence, el SDK no cancela el turno ni cierra conexiones; regresa RUNTIME_CIERRE_TIMEOUT para que la aplicación pueda reintentar el cierre.

Una sesión dañada o deliberadamente descartada se elimina mediante await agent.reset_session(session_id).

Desarrollo

uv sync --all-extras
uv run ruff check .
uv run pyright
uv run pytest
uv build --no-sources

Las pruebas que requieren red son opt-in y no forman parte de la suite normal.

Licencia

Apache License 2.0.