rayito (SDK Python)

Cliente Python de Rayito: sandboxes de ejecución para agentes de IA sobre AWS Lambda MicroVMs, dentro de tu propia cuenta. La ergonomía del SDK de E2B sin que el código de tus clientes salga de tu cuenta y sin clúster que operar. No hay servidor de terceros ni API key: el SDK llama a la API de AWS con tus credenciales.

Documentación: https://alejandro-cedeno-10.github.io/rayito/ · Primeros pasos · Referencia de Python · Changelog

Instalación

pip install "rayito[cli]"      # o: uv add "rayito[cli]"

Python ≥ 3.11. Dependencias de runtime: grpcio, protobuf y boto3. El SDK trae un árbol síncrono (Sandbox) y uno asíncrono (AsyncSandbox) con la misma superficie.

Antes del primer sandbox

Tu cuenta necesita una pila de IAM, un bucket y la imagen rayito-base publicada con el rayd de la misma serie que el SDK. Se hace una vez por cuenta y región con rayito setup, que muestra el plan y el coste y pide confirmación: Configurar AWS.

export AWS_PROFILE=<tu-perfil> AWS_REGION=us-east-1 AWS_DEFAULT_REGION=us-east-1 RAYITO_TEMPLATE=rayito-base
rayito setup --dry-run                   # sólo lectura: plan y coste
rayito setup                             # pila de IAM, bucket e imagen rayito-base
rayito doctor --template rayito-base     # credenciales, cuotas, IAM, imagen, versión del agente

Primer sandbox

from rayito import Sandbox

with Sandbox.create() as sbx:  # `with` mata el sandbox al salir
    print(sbx.commands.run("echo hola").stdout)  # "hola\n"
    sbx.files.write("/home/user/a.txt", "contenido")
    print(sbx.files.read("/home/user/a.txt"))  # "contenido"
    print(sbx.run_code("x = 40; x + 2").text)  # "42"

En asyncio:

import asyncio

from rayito import AsyncSandbox


async def main() -> None:
    async with await AsyncSandbox.create() as sbx:
        print((await sbx.run_code("x = 40; x + 2")).text)  # "42"


asyncio.run(main())

Recorrido completo (comandos, ficheros, código y reconexión desde otro proceso): Primer sandbox.

Si vienes de E2B

rayito.e2b es un drop-in a nivel de import del SDK de E2B 2.x. Lo que Lambda MicroVMs no puede hacer lanza UnimplementedError en vez de aproximarse en silencio. Exige una imagen 0.3.0 o posterior.

from rayito.e2b import Sandbox  # antes: from e2b_code_interpreter import Sandbox

with Sandbox.create(timeout=300, metadata={"run": "42"}) as sbx:
    print(sbx.run_code("1 + 1").text)  # "2"
    sbx.set_timeout(600)

Migrar desde E2B · Diferencias · Paridad

Un agente de código dentro del sandbox

sbx.agent corre un agente de código (OpenCode, o deepagents) dentro del sandbox, sobre la imagen rayito-agent (rayito agent template build). El agente llama a su modelo sólo a través de la pasarela de secretos: usa la credencial, pero nunca puede leerla.

from rayito import AgentModel, AgentSpec, Sandbox, SecretStore, bedrock_gateway

MODEL_ID = "us.anthropic.claude-haiku-4-5-20251001-v1:0"
SecretStore().create("bedrock-key", "Bearer <clave de Bedrock de corta duración>")
spec = AgentSpec(
    model=AgentModel(provider="bedrock", id=MODEL_ID, gateway="bedrock", region="us-east-1")
)

with Sandbox.create(
    template="rayito-agent",
    allow_internet_access=False,
    gateways={"bedrock": bedrock_gateway("bedrock-key", region="us-east-1", models=[MODEL_ID])},
) as sbx:
    result = sbx.agent.run("Lista los ficheros de /home/user y resume qué hay.", spec=spec)
    print(result.text, result.usage.total)

El arranque rápido (PoolConfig(warmup=agent_pool_warmup())) es opcional: ¿Qué uso?. Guía: Agente en el sandbox.

Desplegar tu agente

¿Ya tienes un agente (LangGraph, LangChain, Deep Agents, Strands, Hermes, OpenCode, Vercel AI SDK o tu propia app HTTP)? rayito agent deploy ./mi-agente (o deploy_agent()) detecta el framework, el punto de entrada y el protocolo, y lo sirve desde MicroVMs de tu cuenta; devuelve un AgentFleet para invocarlo. --dry-run muestra el plan sin llamar a AWS.

from rayito import AgentDeployOptions, deploy_agent

fleet = deploy_agent("./mi-agente", options=AgentDeployOptions(bucket="amzn-s3-demo-bucket"))
try:
    reply = fleet.invoke("Resume el README.")
    print(reply.text, reply.session_id)
finally:
    fleet.stop()

Con --target agentcore (o deploy_agent(..., target="agentcore"), que devuelve un AgentCoreFleet) el mismo proyecto va a Amazon Bedrock AgentCore Runtime, sin Docker local. Con rayito[cdk], los constructos RayitoAgent y RayitoMicrovmImage de rayito.cdk hacen lo mismo dentro de tu app de CDK, con cdk deploy. Guías: Despliega tu agente · Desplegar en AgentCore · Desplegar con CDK.

Qué incluye

Funciones opcionales, apagadas por defecto

Cada una crea recursos o hace llamadas facturables en tu cuenta, así que sólo se activa con una opción explícita del SDK o de la CLI; sin ella no se construye ningún cliente de ese servicio. Qué activa, qué cuesta, qué IAM necesita y cómo apagarla: Funciones opcionales.

Costes y límites

Un sandbox factura el cómputo de Lambda MicroVMs mientras corre, más el almacenamiento de cada versión de imagen; Rayito no cobra nada. Precios, ejemplos y tiempos medidos: Precios. Vida máxima, tamaños de payload y la tabla de compatibilidad SDK ↔ rayd: Límites.

Desarrollo

cd clients/python
uv sync
uv run pytest tests/unit
uv run ruff check . && uv run ruff format --check .
uv run mypy src tests
uv build && python ../../scripts/check_wheel.py dist/*.whl   # y `make wheel` desde la raíz: twine con --hash
RAYITO_E2E=1 RAYITO_TEMPLATE=<arn-o-nombre> uv run pytest tests/e2e -m e2e -v -s

Licencia y marcas

Apache-2.0; las atribuciones de terceros están en el fichero NOTICE incluido en el paquete. E2B es una marca de su titular: Rayito es un proyecto independiente, no afiliado, patrocinado ni respaldado por E2B, y usa el nombre sólo para describir la compatibilidad de API del shim. Contribuir: CONTRIBUTING.md; seguridad: SECURITY.md.