> ## 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.

# Démarrage rapide

Ce guide vous aidera à **développer, déployer et appeler votre premier Agent en 5 minutes**.

***

## Table des matières

* [Vue d’ensemble](#overview)
* [Prérequis](#prerequisites)
* [Étape 1 : intégrer le SDK à votre Agent](#step-1-integrate-sdk-into-your-agent)
* [Étape 2 : générer les fichiers de configuration avec la CLI](#step-2-generate-configuration-files-with-cli)
* [Étape 3 : déployer sur Novita en un clic](#step-3-deploy-to-novita-with-one-click)
* [Étape 4 : appeler l’Agent via la CLI ou le SDK](#step-4-invoke-agent-via-cli-or-sdk)
* [FAQ](#faq)

***

## Vue d’ensemble

Le workflow complet se compose de 4 étapes :

1. ✅ **Intégrer le SDK** - Ajoutez des décorateurs au code de votre Agent
2. ✅ **Configurer l’Agent** - Générez les fichiers de configuration à l’aide de la CLI
3. ✅ **Déployer l’Agent** - Déploiement en un clic dans le cloud
4. ✅ **Appeler l’Agent** - Appelez votre Agent à l’aide du SDK ou de la CLI

***

## Prérequis

Assurez-vous de disposer des prérequis suivants :

* ✅ Python 3.9+ et Node.js 20+ installés
* ✅ Version bêta du SDK Python et CLI Node.js installés (voir le [Guide d’installation](/docs/fr/guides/sandbox-agent-runtime-installation))
* ✅ Clé API Novita AI obtenue (depuis la [Console](https://novita.ai/settings/key-management))
* ✅ [Docker](https://www.docker.com/products/docker-desktop/) installé

***

## Étape 1 : intégrer le SDK à votre Agent

### 1.1 Créer le code de l’Agent

Créez `app.py` dans le répertoire de votre projet :

```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 Préparer le fichier de dépendances

Assurez-vous que la racine de votre projet contient un fichier `requirements.txt` avec les dépendances requises :

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

### 1.3 Test local

Testez localement avant le déploiement :

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

Dans un autre terminal, testez les 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!"}'
```

**Sortie attendue** :

Le contrôle d’état doit renvoyer :

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

L’appel de l’Agent doit renvoyer :

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

***

## Étape 2 : générer les fichiers de configuration avec la CLI

Utilisez la CLI pour configurer votre Agent de manière interactive :

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

Suivez les invites de la CLI pour configurer les informations requises. Une fois terminé, la CLI générera les fichiers suivants dans le répertoire de votre projet :

* `novita.Dockerfile` - Fichier de build Docker
* `.dockerignore` - Fichier d’exclusion Docker
* `.novita-agent.yaml` - Fichier de configuration de l’Agent

***

## Étape 3 : déployer sur Novita AI en un clic

> ⚠️ **Important** : après un déploiement réussi, un `agent_id` sera généré. Il s’agit de l’identifiant unique permettant d’appeler votre Agent — veillez à l’enregistrer.

### 3.1 Commande de déploiement

Déployez en un clic à l’aide de la CLI :

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

### 3.2 Afficher les résultats du déploiement

Après un déploiement réussi, le fichier `.novita-agent.yaml` mettra à jour le champ `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
```

**Notez le `agent_id` — vous en aurez besoin pour les appels suivants.**

***

## Étape 4 : appeler l’Agent via la CLI ou le SDK

### Option 1 : test rapide avec la CLI

Testez rapidement votre Agent à l’aide de la CLI :

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

**Remarque** : la CLI lit automatiquement l’ID de l’Agent depuis le champ `status.agent_id` dans `.novita-agent.yaml`.

**Sortie attendue** :

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

### Option 2 : appel via le SDK (recommandé pour la production)

Utilisez le SDK pour appeler votre Agent dans des services backend :

#### Exemple de code

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

***

## FAQ

### Q1 : Comment obtenir l’ID de l’Agent ?

Après un déploiement réussi, l’ID de l’Agent est enregistré dans le champ `status.agent_id` du fichier `.novita-agent.yaml` :

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

### Q2 : Que faire si le déploiement échoue ?

1. **Vérifier le fichier de dépendances** : assurez-vous que `requirements.txt` contient toutes les dépendances
2. **Afficher les journaux détaillés** : utilisez l’option `--verbose`
3. **Vérifier la connexion réseau** : assurez-vous de pouvoir accéder au domaine Novita AI Sandbox (par exemple, `sandbox.novita.ai`)
4. **Vérifier la clé API** : confirmez que `NOVITA_API_KEY` est correct

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

### Q3 : Comment mettre à jour un Agent déployé ?

Modifiez votre code et redéployez :

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

### Q4 : Cela fonctionne localement, mais échoue après le déploiement ?

**Causes possibles** :

1. Variables d’environnement non transmises à l’instance sandbox
2. Incohérences de version des packages de dépendances
3. Problèmes de chemin de fichier

**Solution** :

Transmettez les variables d’environnement à l’instance sandbox via le paramètre `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"
    }
)
```