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

# Schnellstart

Diese Anleitung hilft Ihnen, **Ihren ersten Agent in 5 Minuten zu entwickeln, bereitzustellen und aufzurufen**.

***

## Inhaltsverzeichnis

* [Überblick](#overview)
* [Voraussetzungen](#prerequisites)
* [Schritt 1: SDK in Ihren Agent integrieren](#step-1-integrate-sdk-into-your-agent)
* [Schritt 2: Konfigurationsdateien mit CLI generieren](#step-2-generate-configuration-files-with-cli)
* [Schritt 3: Mit einem Klick auf Novita bereitstellen](#step-3-deploy-to-novita-with-one-click)
* [Schritt 4: Agent über CLI oder SDK aufrufen](#step-4-invoke-agent-via-cli-or-sdk)
* [FAQ](#faq)

***

## Überblick

Der vollständige Workflow besteht aus 4 Schritten:

1. ✅ **SDK integrieren** - Decorators zu Ihrem Agent-Code hinzufügen
2. ✅ **Agent konfigurieren** - Konfigurationsdateien mit CLI generieren
3. ✅ **Agent bereitstellen** - Ein-Klick-Bereitstellung in der Cloud
4. ✅ **Agent aufrufen** - Ihren Agent mit SDK oder CLI aufrufen

***

## Voraussetzungen

Stellen Sie sicher, dass die folgenden Voraussetzungen erfüllt sind:

* ✅ Python 3.9+ und Node.js 20+ installiert
* ✅ Beta-Version des Python SDK und Node.js CLI installiert (siehe [Installationsanleitung](/docs/de/guides/sandbox-agent-runtime-installation))
* ✅ Novita AI API Key erhalten (über die [Console](https://novita.ai/settings/key-management))
* ✅ [Docker](https://www.docker.com/products/docker-desktop/) installiert

***

## Schritt 1: SDK in Ihren Agent integrieren

### 1.1 Agent-Code erstellen

Erstellen Sie `app.py` in Ihrem Projektverzeichnis:

```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 Abhängigkeitsdatei vorbereiten

Stellen Sie sicher, dass Ihr Projektstammverzeichnis eine `requirements.txt`-Datei mit den erforderlichen Abhängigkeiten enthält:

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

### 1.3 Lokales Testen

Testen Sie lokal vor der Bereitstellung:

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

Testen Sie die Endpunkte in einem anderen Terminal:

```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!"}'
```

**Erwartete Ausgabe**:

Der Health Check sollte Folgendes zurückgeben:

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

Der Agent-Aufruf sollte Folgendes zurückgeben:

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

***

## Schritt 2: Konfigurationsdateien mit CLI generieren

Verwenden Sie CLI, um Ihren Agent interaktiv zu konfigurieren:

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

Folgen Sie den CLI-Eingabeaufforderungen, um die erforderlichen Informationen zu konfigurieren. Nach Abschluss generiert die CLI die folgenden Dateien in Ihrem Projektverzeichnis:

* `novita.Dockerfile` - Docker-Build-Datei
* `.dockerignore` - Docker-Ignore-Datei
* `.novita-agent.yaml` - Agent-Konfigurationsdatei

***

## Schritt 3: Mit einem Klick auf Novita AI bereitstellen

> ⚠️ **Wichtig**: Nach erfolgreicher Bereitstellung wird eine `agent_id` generiert. Dies ist die eindeutige Kennung zum Aufrufen Ihres Agent—speichern Sie sie unbedingt.

### 3.1 Bereitstellungsbefehl

Stellen Sie mit einem Klick über CLI bereit:

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

### 3.2 Bereitstellungsergebnisse anzeigen

Nach erfolgreicher Bereitstellung aktualisiert die Datei `.novita-agent.yaml` das Feld `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
```

**Notieren Sie die `agent_id`—Sie benötigen sie für nachfolgende Aufrufe.**

***

## Schritt 4: Agent über CLI oder SDK aufrufen

### Option 1: Schnelltest mit CLI

Testen Sie Ihren Agent schnell mit CLI:

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

**Hinweis**: Die CLI liest die Agent ID automatisch aus dem Feld `status.agent_id` in `.novita-agent.yaml`.

**Erwartete Ausgabe**:

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

### Option 2: SDK-Aufruf (für Produktion empfohlen)

Verwenden Sie das SDK, um Ihren Agent in Backend-Diensten aufzurufen:

#### Beispielcode

```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: Wie erhalte ich die Agent ID?

Nach erfolgreicher Bereitstellung wird die Agent ID im Feld `status.agent_id` der Datei `.novita-agent.yaml` gespeichert:

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

### Q2: Was ist, wenn die Bereitstellung fehlschlägt?

1. **Abhängigkeitsdatei prüfen**: Stellen Sie sicher, dass `requirements.txt` alle Abhängigkeiten enthält
2. **Detaillierte Logs anzeigen**: Verwenden Sie das Flag `--verbose`
3. **Netzwerkverbindung prüfen**: Stellen Sie sicher, dass Sie auf die Novita AI Sandbox-Domain zugreifen können (z. B. `sandbox.novita.ai`)
4. **API Key überprüfen**: Bestätigen Sie, dass `NOVITA_API_KEY` korrekt ist

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

### Q3: Wie aktualisiere ich einen bereitgestellten Agent?

Ändern Sie Ihren Code und stellen Sie ihn erneut bereit:

```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: Funktioniert lokal, schlägt aber nach der Bereitstellung fehl?

**Mögliche Ursachen**:

1. Umgebungsvariablen werden nicht an die Sandbox-Instanz übergeben
2. Inkonsistenzen bei Versionen von Abhängigkeitspaketen
3. Probleme mit Dateipfaden

**Lösung**:

Übergeben Sie Umgebungsvariablen über den Parameter `envVars` an die Sandbox-Instanz:

```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"
    }
)
```