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

# Início Rápido

Este guia ajudará você a **desenvolver, implantar e invocar seu primeiro Agente em 5 minutos**.

***

## Sumário

* [Visão geral](#overview)
* [Pré-requisitos](#prerequisites)
* [Etapa 1: Integre o SDK ao seu Agente](#step-1-integrate-sdk-into-your-agent)
* [Etapa 2: Gere arquivos de configuração com a CLI](#step-2-generate-configuration-files-with-cli)
* [Etapa 3: Implante na Novita com um clique](#step-3-deploy-to-novita-with-one-click)
* [Etapa 4: Invoque o Agente via CLI ou SDK](#step-4-invoke-agent-via-cli-or-sdk)
* [FAQ](#faq)

***

## Visão geral

O fluxo de trabalho completo consiste em 4 etapas:

1. ✅ **Integrar o SDK** - Adicione decorators ao código do seu Agente
2. ✅ **Configurar o Agente** - Gere arquivos de configuração usando a CLI
3. ✅ **Implantar o Agente** - Implantação na nuvem com um clique
4. ✅ **Invocar o Agente** - Chame seu Agente usando SDK ou CLI

***

## Pré-requisitos

Certifique-se de ter os seguintes pré-requisitos:

* ✅ Python 3.9+ e Node.js 20+ instalados
* ✅ Versão beta do Python SDK e da Node.js CLI instalada (consulte o [Guia de Instalação](/docs/pt-BR/guides/sandbox-agent-runtime-installation))
* ✅ Chave de API da Novita AI obtida (no [Console](https://novita.ai/settings/key-management))
* ✅ [Docker](https://www.docker.com/products/docker-desktop/) instalado

***

## Etapa 1: Integre o SDK ao seu Agente

### 1.1 Criar o código do Agente

Crie `app.py` no diretório do seu projeto:

```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 o arquivo de dependências

Certifique-se de que a raiz do seu projeto tenha um arquivo `requirements.txt` com as dependências necessárias:

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

### 1.3 Testes locais

Teste localmente antes da implantação:

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

Em outro terminal, teste os 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!"}'
```

**Saída esperada**:

A verificação de integridade deve retornar:

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

A invocação do Agente deve retornar:

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

***

## Etapa 2: Gere arquivos de configuração com a CLI

Use a CLI para configurar seu Agente de forma interativa:

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

Siga as instruções da CLI para configurar as informações necessárias. Ao concluir, a CLI gerará os seguintes arquivos no diretório do seu projeto:

* `novita.Dockerfile` - Arquivo de build do Docker
* `.dockerignore` - Arquivo de ignore do Docker
* `.novita-agent.yaml` - Arquivo de configuração do Agente

***

## Etapa 3: Implante na Novita AI com um clique

> ⚠️ **Importante**: Após a implantação bem-sucedida, um `agent_id` será gerado. Este é o identificador único para invocar seu Agente — certifique-se de salvá-lo.

### 3.1 Comando de implantação

Implante com um clique usando a CLI:

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

### 3.2 Ver resultados da implantação

Após a implantação bem-sucedida, o arquivo `.novita-agent.yaml` atualizará o 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
```

**Registre o `agent_id` — você precisará dele para invocações subsequentes.**

***

## Etapa 4: Invoque o Agente via CLI ou SDK

### Opção 1: Teste rápido com a CLI

Teste rapidamente seu Agente usando a CLI:

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

**Observação**: A CLI lê automaticamente o ID do Agente do campo `status.agent_id` em `.novita-agent.yaml`.

**Saída esperada**:

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

### Opção 2: Invocação com SDK (recomendado para produção)

Use o SDK para invocar seu Agente em serviços backend:

#### Código de exemplo

```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: Como obtenho o ID do Agente?

Após a implantação bem-sucedida, o ID do Agente é salvo no campo `status.agent_id` do arquivo `.novita-agent.yaml`:

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

### Q2: E se a implantação falhar?

1. **Verifique o arquivo de dependências**: Certifique-se de que `requirements.txt` contenha todas as dependências
2. **Veja logs detalhados**: Use a flag `--verbose`
3. **Verifique a conexão de rede**: Certifique-se de que você consiga acessar o domínio do Novita AI Sandbox (por exemplo, `sandbox.novita.ai`)
4. **Verifique a chave de API**: Confirme se `NOVITA_API_KEY` está correta

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

### Q3: Como atualizo um Agente implantado?

Modifique seu código e implante novamente:

```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: Funciona localmente, mas falha após a implantação?

**Possíveis causas**:

1. Variáveis de ambiente não passadas para a instância de sandbox
2. Inconsistências nas versões dos pacotes de dependência
3. Problemas de caminho de arquivo

**Solução**:

Passe variáveis de ambiente para a instância de sandbox por meio do 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"
    }
)
```