> ## Documentation Index
> Fetch the complete documentation index at: https://novita.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Inicio rápido

Esta guía te ayudará a **desarrollar, desplegar e invocar tu primer Agent en 5 minutos**.

***

## Tabla de contenidos

* [Descripción general](#overview)
* [Requisitos previos](#prerequisites)
* [Paso 1: Integra el SDK en tu Agent](#step-1-integrate-sdk-into-your-agent)
* [Paso 2: Genera archivos de configuración con la CLI](#step-2-generate-configuration-files-with-cli)
* [Paso 3: Despliega en Novita con un solo clic](#step-3-deploy-to-novita-with-one-click)
* [Paso 4: Invoca el Agent mediante CLI o SDK](#step-4-invoke-agent-via-cli-or-sdk)
* [Preguntas frecuentes](#faq)

***

## Descripción general

El flujo de trabajo completo consta de 4 pasos:

1. ✅ **Integrar el SDK** - Añade decoradores al código de tu Agent
2. ✅ **Configurar el Agent** - Genera archivos de configuración usando la CLI
3. ✅ **Desplegar el Agent** - Despliegue en la nube con un solo clic
4. ✅ **Invocar el Agent** - Llama a tu Agent usando el SDK o la CLI

***

## Requisitos previos

Asegúrate de cumplir los siguientes requisitos previos:

* ✅ Python 3.9+ y Node.js 20+ instalados
* ✅ Versión beta del SDK de Python y la CLI de Node.js instaladas (consulta la [Guía de instalación](/docs/es/guides/sandbox-agent-runtime-installation))
* ✅ Clave de API de Novita AI obtenida (desde la [Consola](https://novita.ai/settings/key-management))
* ✅ [Docker](https://www.docker.com/products/docker-desktop/) instalado

***

## Paso 1: Integra el SDK en tu Agent

### 1.1 Crear el código del Agent

Crea `app.py` en el directorio de tu proyecto:

```python theme={"system"}
from novita_sandbox.agent_runtime import AgentRuntimeApp

# Create Agent Runtime application instance
app = AgentRuntimeApp()

# Define Agent entry point with decorator
@app.entrypoint
def my_agent(request: dict) -> dict:
    """
    Agent entry function
    
    Args:
        request: Request data, which typically contains fields like prompt
        
    Returns:
        Response data dictionary
    """
    prompt = request.get("prompt", "")
    
    # Agent business logic
    # You can call LLMs, use Agent frameworks, or implement any custom logic here
    result = f"Received message: {prompt}"
    
    return {"result": result}

# Local run entry point
if __name__ == "__main__":
    app.run()
```

### 1.2 Preparar el archivo de dependencias

Asegúrate de que la raíz de tu proyecto tenga un archivo `requirements.txt` con las dependencias requeridas:

```txt theme={"system"}
novita-sandbox>=1.1.0b1
# Your other dependencies...
```

### 1.3 Pruebas locales

Haz pruebas localmente antes del despliegue:

```bash theme={"system"}
# Start the Agent service
python app.py
```

En otra terminal, prueba los endpoints:

```bash theme={"system"}
# Test health check
curl http://localhost:8080/ping

# Test Agent invocation
curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello, Agent!"}'
```

**Salida esperada**:

La comprobación de estado debería devolver:

```json theme={"system"}
{"status": "Healthy"}
```

La invocación del Agent debería devolver:

```json theme={"system"}
{"result": "Received message: Hello, Agent!"}
```

***

## Paso 2: Genera archivos de configuración con la CLI

Usa la CLI para configurar tu Agent de forma interactiva:

```bash theme={"system"}
# Make sure environment variables are configured
export NOVITA_API_KEY=your-novita-api-key

# Run configuration command
npx novita-sandbox-cli agent configure
```

Sigue las indicaciones de la CLI para configurar la información requerida. Al finalizar, la CLI generará los siguientes archivos en el directorio de tu proyecto:

* `novita.Dockerfile` - Archivo de compilación de Docker
* `.dockerignore` - Archivo de exclusión de Docker
* `.novita-agent.yaml` - Archivo de configuración del Agent

***

## Paso 3: Despliega en Novita AI con un solo clic

> ⚠️ **Importante**: Tras un despliegue correcto, se generará un `agent_id`. Este es el identificador único para invocar tu Agent; asegúrate de guardarlo.

### 3.1 Comando de despliegue

Despliega con un solo clic usando la CLI:

```bash theme={"system"}
npx novita-sandbox-cli agent launch
```

### 3.2 Ver los resultados del despliegue

Tras un despliegue correcto, el archivo `.novita-agent.yaml` actualizará el campo `status`:

```yaml theme={"system"}
status:
  phase: deployed
  agent_id: agent-xxxx  # ⭐ This is your Agent's unique identifier
  last_deployed: '2025-10-23T10:35:00Z'
  build_id: build_xyz789
```

**Registra el `agent_id`; lo necesitarás para las invocaciones posteriores.**

***

## Paso 4: Invoca el Agent mediante CLI o SDK

### Opción 1: Prueba rápida con la CLI

Prueba rápidamente tu Agent usando la CLI:

```bash theme={"system"}
npx novita-sandbox-cli agent invoke "Hello, Agent!"
```

**Nota**: La CLI lee automáticamente el ID del Agent desde el campo `status.agent_id` en `.novita-agent.yaml`.

**Salida esperada**:

```json theme={"system"}
{"result": "Received message: Hello, Agent!"}
```

### Opción 2: Invocación con SDK (recomendado para producción)

Usa el SDK para invocar tu Agent en servicios backend:

#### Código de ejemplo

```python theme={"system"}
import asyncio
import json
import os
from novita_sandbox.agent_runtime import AgentRuntimeClient
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Create Agent Runtime client
client = AgentRuntimeClient(
    api_key=os.getenv("NOVITA_API_KEY")
)

async def main():
    # Get from status.agent_id in .novita-agent.yaml after deployment
    agent_id = "agent-xxxx"
    
    # Prepare request data
    payload = json.dumps({
        "prompt": "Hello, Agent! Tell me something about AI."
    }).encode()
    
    # Invoke Agent
    print(f"🚀 Invoking agent: {agent_id}")
    response = await client.invoke_agent_runtime(
        agentId=agent_id,
        payload=payload,
        timeout=300
    )
    
    print(f"✅ Response: {response}")

if __name__ == "__main__":
    asyncio.run(main())
```

***

## Preguntas frecuentes

### P1: ¿Cómo obtengo el ID del Agent?

Tras un despliegue correcto, el ID del Agent se guarda en el campo `status.agent_id` del archivo `.novita-agent.yaml`:

```yaml theme={"system"}
status:
  agent_id: agent-xxxxx  # Here
```

### P2: ¿Qué ocurre si falla el despliegue?

1. **Comprueba el archivo de dependencias**: Asegúrate de que `requirements.txt` contenga todas las dependencias
2. **Consulta los registros detallados**: Usa la marca `--verbose`
3. **Comprueba la conexión de red**: Asegúrate de que puedes acceder al dominio Novita AI Sandbox (por ejemplo, `sandbox.novita.ai`)
4. **Verifica la clave de API**: Confirma que `NOVITA_API_KEY` sea correcta

```bash theme={"system"}
# Show detailed logs
npx novita-sandbox-cli agent launch --verbose
```

### P3: ¿Cómo actualizo un Agent desplegado?

Modifica tu código y vuelve a desplegar:

```bash theme={"system"}
# Option 1: Create new version (Recommended)
npx novita-sandbox-cli agent configure --agent-version 1.1.0
npx novita-sandbox-cli agent launch

# Option 2: Update existing version
npx novita-sandbox-cli agent launch --update-existing
```

### P4: ¿Funciona localmente pero falla después del despliegue?

**Posibles causas**:

1. Variables de entorno no pasadas a la instancia de sandbox
2. Inconsistencias en las versiones de los paquetes de dependencias
3. Problemas con rutas de archivos

**Solución**:

Pasa las variables de entorno a la instancia de sandbox mediante el parámetro `envVars`:

```python theme={"system"}
response = await client.invoke_agent_runtime(
    agentId=agent_id,
    payload=payload,
    envVars={
        "NOVITA_API_KEY": os.getenv("NOVITA_API_KEY"),
        "MODEL_NAME": "deepseek/deepseek-v3-0324"
    }
)
```