AgentBay:AgentBay CLI

Principais recursos

• Gerenciamento de autenticação: Integra-se à sua conta Alibaba Cloud por meio de um mecanismo seguro de login baseado em OAuth.

• Gerenciamento de imagens: Navegue, crie, ative, desative e exclua imagens personalizadas, além de visualizar o status das imagens.

• Criação de imagens: Oferece suporte aos modos de build na nuvem e local.

• Ativação de imagens: Ative instâncias de imagens personalizadas com recursos personalizados, configurações de rede e gerenciamento de ciclo de vida.

• Desativação de imagens: Desative instâncias de imagens ativas para liberar recursos.

• Download de modelos: Baixe modelos de Dockerfile da nuvem.

• Gerenciamento de chaves de API: Crie chaves de API e defina limites de concorrência.

• Gerenciamento de Skills: Envie Skills locais para a nuvem e visualize seus detalhes por ID.

• Gerenciamento de configuração: Armazena tokens com segurança e os renova automaticamente.

• Gerenciamento de rede: Liste os pacotes de rede criados.

• Status da imagem: Visualize o status de build e de recursos das imagens.

Tipos de imagem suportados

Atualmente, a ferramenta CLI suporta apenas a criação e ativação de imagens personalizadas do tipo CodeSpace. A coluna TYPE na saída do comando image list exibe a categoria subjacente, como DockerBuilder ou DedicatedDesktop, mas essa informação não é relevante para as operações da CLI.

Instalar com tap (recomendado)

# 1. Add the AgentBay Cloud Homebrew Tap
brew tap aliyun/agentbay

# 2. Install the agentbay command-line tool
brew install agentbay

# 3. Verify the installation
agentbay version
            

# Check the version information
agentbay version

# View help
agentbay --help

# Run an AgentBay command
agentbay [command] [options]
            

# Method 1: Upgrade only agentbay
brew upgrade agentbay

# Method 2: Try this if Method 1 fails
git -C $(brew --repository aliyun/agentbay) pull && brew upgrade agentbay

# Method 3: Try this if the first two methods fail
brew update
brew reinstall agentbay
            

# Uninstall agentbay
brew uninstall agentbay

# Remove the Tap (optional)
brew untap aliyun/agentbay
            

# Update Homebrew
brew update

# Clean the cache
brew cleanup

# Reinstall
brew reinstall agentbay
              

# Set a Go proxy
export GOPROXY=https://goproxy.cn,direct
export GOSUMDB=sum.golang.google.cn

# Reinstall
brew reinstall agentbay
              

# Fix Homebrew permissions
sudo chown -R $(whoami) $(brew --prefix)/*
              

Instalação manual

Baixe a versão mais recente para sua plataforma na página de GitHub Releases.

Etapa 1: Fazer login

A CLI abre seu navegador para autenticação no Alibaba Cloud e retorna ao terminal após o login.

agentbay login

Etapa 2: Visualizar imagens disponíveis

# List only custom images (default)
agentbay image list

# Include system and custom images
agentbay image list --include-system

# Display only system images
agentbay image list --system-only

Etapa 3: Baixar um modelo de Dockerfile

Baixe um modelo de Dockerfile para o diretório atual. Especifique o ID da imagem de origem. Para listar os IDs das imagens de sistema disponíveis, execute agentbay image list --system-only:

agentbay image init --sourceImageId code-space-debian-12

Etapa 4: Criar uma imagem personalizada

agentbay image create myapp --dockerfile Dockerfile --imageId code-space-debian-12

Etapa 5: Ativar uma imagem

Ative imagens personalizadas antes da implantação. Imagens de sistema não exigem ativação.

agentbay image activate imgc-xxxxx...xxx

Etapa 6: Desativar uma imagem

Desative uma imagem personalizada quando ela não for mais necessária para liberar os recursos alocados.

agentbay image deactivate imgc-xxxxx...xxx

Etapa 7: Criar uma chave de API

agentbay apikey create --name "my-api-key"

Etapa 8: Definir a concorrência da sessão

agentbay apikey concurrency set --api-key-id ak-xxx --concurrency 10

Opções globais

Todos os comandos aceitam estas opções globais:

• --help, -h: Exibe a ajuda do comando.

• --verbose, -v: Mostra saídas detalhadas de depuração.

• --version: Exibe a versão da CLI.

Estrutura dos comandos

agentbay [global options] <command> [command options] [arguments]

Índice de comandos

Comandos do AgentBay CLI agrupados por função:

Ativação e desativação de imagens

• Imagens personalizadas: Devem ser ativadas antes da implantação.

• Imagens de sistema: Estão sempre disponíveis e não requerem ativação.

• Desativação de imagem: Desative uma imagem personalizada quando não for mais necessária para liberar seus recursos computacionais.

Listagem de imagens

Lista as imagens disponíveis no AgentBay.

Sintaxe

agentbay image list [options]

Opções

• --os-type, -o <type>: Filtra pelo tipo de sistema operacional (Linux, Android ou Windows).

• --include-system: Exibe tanto imagens personalizadas quanto imagens de sistema.

• --system-only: Exibe apenas imagens de sistema.

• --page, -p <number>: Número da página (padrão: 1).

• --size, -s <number>: Quantidade de itens a serem exibidos por página (padrão: 10).

Exemplos

# List custom images
agentbay image list

# List Linux images
agentbay image list --os-type Linux

# List all images (custom + system)
agentbay image list --include-system

# List only system images
agentbay image list --system-only

# Query with pagination
agentbay image list --page 2 --size 5

Descrição da saída

A saída inclui as seguintes colunas:

• Image ID: Identificador exclusivo da imagem.

• Image name: Nome da imagem.

• Type: Tipo da imagem (DockerBuilder ou DedicatedDesktop).

• Status: Status atual da imagem.

• OS: Tipo e versão do sistema operacional.

• Use case: Caso de uso da imagem.

Descrição dos status

• Creating: A imagem está sendo criada.

• Available: O build da imagem foi concluído e ela está pronta para ativação.

• Activated: A imagem está ativada e em execução.

• Create Failed: O build da imagem falhou.

Inicialização de imagem

Baixa um modelo de Dockerfile para o diretório atual referente a uma imagem base especificada.

Sintaxe

agentbay image init --sourceImageId <image-id>

Exemplo

# Download a Dockerfile template
agentbay image init --sourceImageId code-space-debian-12

Exemplo de saída

[INIT] Downloading Dockerfile template...
Requesting Dockerfile template... Done.
Downloading Dockerfile from OSS... Done.
Writing Dockerfile to /path/to/current/directory/Dockerfile...
[WARN] Dockerfile already exists at /path/to/current/directory/Dockerfile
[INFO] The existing file will be overwritten.
 Done.
[SUCCESS] Dockerfile template downloaded successfully!
[INFO] Dockerfile saved to: /path/to/current/directory/Dockerfile
[IMPORTANT] The first 5 line(s) of the Dockerfile are system-defined and cannot be modified.
[IMPORTANT] Please only modify content after line 5.

Criação de imagem

Cria uma nova imagem do AgentBay a partir de um Dockerfile.

Sintaxe

agentbay image create <image-name> --dockerfile <path> --imageId <base-image-id>

Argumentos

• <image-name>: Nome da imagem personalizada (obrigatório).

Opções

• --dockerfile, -f <path>: Caminho para o Dockerfile (obrigatório).

• --imageId, -i <id>: ID da imagem base (obrigatório).

Exemplos

# Use full option names
agentbay image create my-app --dockerfile ./Dockerfile --imageId code-space-debian-12

# Use short option names
agentbay image create my-app -f ./Dockerfile -i code-space-debian-12

# Use verbose output mode
agentbay image create my-app -f ./Dockerfile -i code-space-debian-12 -v

Exemplo de saída

[BUILD] Creating image 'my-app'...
[STEP 1/4] Getting upload credentials... Done.
[STEP 2/4] Uploading Dockerfile... Done.
[STEP 3/4] Uploading ADD/COPY files (N files)... Done.
[STEP 4/4] Creating Docker image task... Done.
[STEP 5/5] Building image (Task ID: task-xxxxx)...
[STATUS] Build status: RUNNING
[SUCCESS] Image created successfully!
[RESULT] Image ID: imgc-xxxxx...xxx

Processo de build

1. Obtém credenciais de upload.

2. Envia o Dockerfile para o armazenamento de objetos.

3. Envia arquivos referenciados pelas instruções ADD/COPY, caso existam no Dockerfile.

4. Cria uma tarefa de build de imagem Docker.

5. Inicia o build da imagem.

Upload de arquivos ADD/COPY

Ao criar uma imagem, a CLI analisa as instruções COPY e ADD no Dockerfile e envia os arquivos locais referenciados. Os caminhos são relativos ao diretório que contém o Dockerfile. Há suporte para arquivos únicos, múltiplos arquivos, subdiretórios e curingas (como *.py). Caminhos absolutos, travessia de diretórios (como ../) e fontes URL para a instrução ADD não são suportados. Todos os arquivos referenciados por COPY ou ADD devem existir no diretório do Dockerfile ou em seus subdiretórios.

Ativação de imagem

Ativa uma imagem personalizada para torná-la disponível para implantação.

Sintaxe

agentbay image activate <image-id> [options]

Argumentos

• <image-id>: ID da imagem a ser ativada (obrigatório).

Opções

• --cpu, -c <cores>: Número de núcleos de CPU (2, 4, 8 ou 16).

• --memory, -m <GB>: Quantidade de memória em GB (4, 8, 16 ou 32).

• --network-type: Especifica o tipo de rede. Use ADVANCED para rede avançada ou DEFAULT para rede básica. Se não especificado, assume a rede básica.

• --session-bandwidth: Define a largura de banda pública máxima por sessão, em Mbps. O valor deve estar entre 2 e 200. Esta opção aplica-se apenas à rede avançada. Se não especificada, a largura de banda será ilimitada.

• --dns-address: Endereço IP de um servidor DNS. Esta opção está disponível apenas para a rede avançada e é opcional. É possível especificar esta opção várias vezes para configurar múltiplos servidores DNS.

• --lifecycle-mode: Define o modo de liberação para o ciclo de vida do sandbox. No modo auto, os recursos computacionais são liberados automaticamente com base nas políticas de ciclo de vida. No modo manual, você deve desativar a imagem para liberar os recursos.

• --lifecycle-max-runtime: Tempo máximo de execução em minutos. Requer que --lifecycle-mode esteja definido como auto.

• --lifecycle-hibernate: Duração máxima de hibernação em horas. Requer que --lifecycle-mode esteja definido como auto.

• --lifecycle-idle-timeout: Duração máxima de ociosidade em minutos. Requer que --lifecycle-mode esteja definido como auto.

Configurações de recursos suportadas

• 2c4g: 2 núcleos de CPU, 4 GB de memória (configuração padrão se não especificado).

• 4c8g: 4 núcleos de CPU, 8 GB de memória.

• 8c16g: 8 núcleos de CPU, 16 GB de memória.

• 16c32g: 16 núcleos de CPU, 32 GB de memória.

Exemplos

# Activate with the default resource configuration (2c4g)
agentbay image activate imgc-xxxxx...xxx

# Activate with a 2c4g configuration
agentbay image activate imgc-xxxxx...xxx --cpu 2 --memory 4

# Activate with a 4c8g configuration
agentbay image activate imgc-xxxxx...xxx --cpu 4 --memory 8

# Activate with an 8c16g configuration
agentbay image activate imgc-xxxxx...xxx --cpu 8 --memory 16

# Activate with a 16c32g configuration
agentbay image activate imgc-xxxxx...xxx --cpu 16 --memory 32

# Use verbose output
agentbay image activate imgc-xxxxx...xxx --cpu 4 --memory 8 -v

# Advanced network - minimal form
agentbay image activate imgc-xxxx --network-type ADVANCED

# Advanced network - with bandwidth configuration
agentbay image activate imgc-xxxx --network-type ADVANCED --session-bandwidth 10

# Advanced network - with DNS configuration
agentbay image activate imgc-xxxx \
  --network-type ADVANCED \
  --dns-address 8.8.8.8 \
  --dns-address 8.8.4.4

# Advanced network - full configuration
agentbay image activate imgc-xxxx \
  --cpu 8 \
  --memory 16 \
  --network-type ADVANCED \
  --session-bandwidth 10 \
  --dns-address 8.8.8.8 \
  --dns-address 114.114.114.114

# Sandbox lifecycle - manual release
agentbay image activate imgc-xxxx --lifecycle-mode manual

# Sandbox lifecycle - automatic release with max runtime
agentbay image activate imgc-xxx --lifecycle-mode auto --lifecycle-max-runtime 30

# Sandbox lifecycle - full configuration
agentbay image activate imgc-xxxx \
  --lifecycle-mode auto \
  --lifecycle-max-runtime 50 \
  --lifecycle-hibernate 40 \
  --lifecycle-idle-timeout 30

Exemplo de saída

[ACTIVATE] Activating image...
Checking current image status... Done.
Creating resource group... Done.
Waiting for activation to complete...
  Status: Activating (elapsed: 5s, attempt: 2/60)
  Status: Activating (elapsed: 13s, attempt: 3/60)
[SUCCESS] Image activated successfully!

Notas de uso

• Somente imagens personalizadas podem ser ativadas.

• Imagens de sistema estão sempre disponíveis e não requerem ativação.

• As opções --cpu e --memory devem ser especificadas juntas e corresponder a uma configuração suportada.

• Se você omitir as opções de CPU e memória, a configuração padrão (2c4g) será utilizada.

• O processo de ativação geralmente leva de 1 a 2 minutos.

• Se a imagem já estiver ativada, o comando informará que nenhuma ação é necessária.

• Durante a ativação, o comando consulta periodicamente o status da imagem. O intervalo de consulta aumenta com o tempo. O comando faz até 60 tentativas com um tempo limite total de 30 minutos.

Desativação de imagem

Desativa uma imagem personalizada ativa e libera seus recursos associados.

Sintaxe

agentbay image deactivate <image-id>

Argumentos

• <image-id>: ID da imagem a ser desativada (obrigatório).

Exemplos

# Deactivate an image
agentbay image deactivate imgc-xxxxx...xxx

# Use verbose output
agentbay image deactivate imgc-xxxxx...xxx -v

Exemplo de saída

[DEACTIVATE] Deactivating image...
Deleting resource group... Done.
Waiting for deactivation to complete...
  Status: Deactivating (elapsed: 5s, attempt: 2/40)
[SUCCESS] Image deactivated successfully!

Notas de uso

• A desativação geralmente leva de 1 a 2 minutos. O comando consulta o status da imagem até 40 vezes, com um tempo limite total de cerca de 20 minutos.

• Após a conclusão da desativação, execute agentbay image list para confirmar que os recursos foram liberados.

• Desativar uma imagem libera os recursos computacionais associados e interrompe o faturamento.

Exclusão de imagem

Exclui permanentemente uma imagem personalizada. Esta ação é irreversível.

Pré-requisitos

Desative a imagem para liberar seus recursos computacionais antes de excluí-la. Execute agentbay image deactivate <image-id>.

Sintaxe

agentbay image delete <image-id>

Argumentos

• <image-id>: ID da imagem a ser excluída (obrigatório).

Exemplos

# 1. First, deactivate the image (prerequisite)
agentbay image deactivate imgc-xxxxxxxxxxxxxx

# 2. Delete interactively (prompts for y/N confirmation)
agentbay image delete imgc-xxxxxxxxxxxxxx

# 3. Skip confirmation in a script or CI environment
agentbay image delete imgc-xxxxxxxxxxxxxx --yes

# 4. Verify the deletion (the image no longer appears in the list)
agentbay image list

Exemplo de saída

[DELETE] Deleting image 'imgc-0ab5ta4nzbwu9bvaa'...
Checking current image status... Done.
[INFO] GetMcpImageInfo Request ID: 3DFFDC7F-9EC2-10BA-878B-EE1E54D00245
[INFO] Image Type: User
[INFO] Current Status: Available (Deactivated)
Are you sure you want to permanently delete image 'imgc-0ab5ta4nzbwu9bvaa'? This action is irreversible. [y/N]: y
Deleting image... Done.
[INFO] DeleteMcpImage Request ID: 2EB74FE6-5757-167F-B71E-0C474ED0419B
[SUCCESS] Image 'imgc-0ab5ta4nzbwu9bvaa' has been permanently deleted.

Status da imagem

Exibe o status detalhado de build e de recursos de uma imagem específica.

Sintaxe

agentbay image status <image-id>

Argumentos

• <image-id>: ID da imagem cujo status deseja visualizar (obrigatório).

Exemplo

agentbay image status imgc-xxxxx...xxx

Descrição dos status

O status da imagem divide-se em duas categorias: status de build e status de recursos.

network package list — Listar pacotes de rede

Sintaxe

agentbay network package list [options]

Opções

• --biz-region-id <region-id>: ID da região (padrão: cn-hangzhou).

Exemplos

# List network packages in the default China (Hangzhou) region
agentbay network package list

# Query network packages in another region
agentbay network package list --biz-region-id cn-shanghai

Saída

A saída inclui as seguintes colunas:

• Network package ID: Identificador exclusivo do pacote de rede.

• Office site ID: ID do site de escritório associado.

• EIP addresses: Endereços IP elásticos (EIPs) vinculados.

Notas de uso

apikey create

Sintaxe

agentbay apikey create --name <name>

Opções

• --name <name>: Nome da chave de API (obrigatório).

Exemplo

agentbay apikey create --name "my-api-key"

Exemplo de saída

API Key created successfully.
  ID:      ak-xxxxxxxxxxxx
  Name:    my-api-key
  Created: 2025-01-15 10:30:00

Verificação

Após a criação, execute agentbay apikey list para visualizar suas chaves de API.

apikey concurrency set

Sintaxe

agentbay apikey concurrency set --api-key-id <api-key-id> --concurrency <number>

Opções

• --api-key-id <api-key-id>: ID da chave de API (obrigatório).

• --concurrency <number>: Limite de concorrência, que deve ser igual ou superior a 1 (obrigatório).

Exemplo

agentbay apikey concurrency set --api-key-id ak-xxxxx --concurrency 5

Verificação

Visualize os detalhes da chave de API para confirmar o novo limite de concorrência.

skills — Grupo de comandos de Skill

Sintaxe

agentbay skills <subcommand> [parameters] [options]

Subcomandos

• push: Envia uma skill local (um diretório ou um arquivo .zip) para a nuvem.

• show: Exibe detalhes de uma skill especificada.

Opções globais (compartilhadas com subcomandos)

• --verbose, -v: Habilita saída detalhada, exibindo informações de depuração como URL de upload, tamanho do upload e RequestId.

• --help: Exibe informações de ajuda.

skills push — Enviar uma skill

Envia uma skill local para a nuvem. A CLI obtém uma credencial de upload, envia o arquivo zip e cria a skill. Forneça o diretório raiz da skill (contendo um arquivo SKILL.md) ou um arquivo .zip pré-empacotado.

Sintaxe

agentbay skills push <skill-dir>|<skill.zip>

Parâmetros

• <skill-dir>: Caminho para o diretório raiz da skill. O diretório deve conter um arquivo SKILL.md. A CLI valida os metadados obrigatórios e então empacota o diretório em um arquivo zip para upload.

• <skill.zip>: Caminho para um arquivo zip. O arquivo é enviado tal como está.

Requisitos do SKILL.md (modo diretório)

• Deve incluir uma linha name: especificando o nome da skill (obrigatório). Por exemplo: name: my-skill.

• Também é possível incluir uma linha description: para fornecer a descrição da skill.

• Recomenda-se o uso de front matter no estilo YAML:

---
name: my-skill
description: Optional description
---

# Skill content

Nomeação do arquivo enviado

• Modo diretório: O nome do arquivo zip é formado adicionando .zip ao nome base do diretório. Por exemplo, para o diretório ./pdf, o nome do arquivo enviado será pdf.zip. Se o nome base estiver vazio ou for ., será usado skill.zip.

• Modo Zip: O nome do arquivo zip fornecido é utilizado exatamente como está.

Fluxo de execução

1. [STEP 1/3] Obter uma credencial de upload, como uma URL pré-assinada.

2. [STEP 2/3] Enviar o arquivo: Diretórios são compactados em zip antes do envio; arquivos zip são enviados diretamente.

3. [STEP 3/3] Chamar a API Create Skill. Em caso de sucesso, o comando imprime o ID da skill resultante.

Exemplos

# Push from a directory containing SKILL.md
agentbay skills push ./my-skill

# Push a pre-packaged zip file
agentbay skills push ./my-skill.zip

# Use verbose output
agentbay skills push ./my-skill -v

Exemplo de saída

[STEP 1/3] Getting upload credential...
[STEP 2/3] Packing and uploading skill...
[STEP 3/3] Creating skill...

[SUCCESS] Skill created successfully!
[RESULT] Skill ID: <skill-id>

skills show — Mostrar detalhes da skill

Exibe os detalhes de uma skill especificada.

Sintaxe

agentbay skills show <skill-id>

Parâmetros

• <skill-id>: Identificador exclusivo da skill. Este é o ID retornado na saída [RESULT] de um comando skills push bem-sucedido.

Saída

• Skill ID: Identificador exclusivo da skill.

• Name, description: Nome e descrição da skill. Descrições longas sofrem quebra de linha e recuo automático para melhor legibilidade.

Exemplos

# Show Skill details
agentbay skills show <skill-id>

# Show verbose output
agentbay skills show <skill-id> -v

login

Sintaxe

agentbay login

Processo de login

1. Inicia um servidor de callback local.

2. Abre o navegador para autenticação no Alibaba Cloud.

3. Recebe um código de autorização e o troca por um token de acesso.

4. Salva os tokens de autenticação em um arquivo de configuração local.

Exemplo de saída

Starting AgentBay authentication...
Starting local callback server on port 3001...
Opening browser for authentication...
Browser opened successfully!
Waiting for callback on http://localhost:3001/callback...
Authentication successful!
Received authorization code: xxxxx...
Exchanging authorization code for access token...
Saving authentication tokens...
Authentication tokens saved successfully!
You are now logged in to AgentBay!

Solução de problemas

Se a porta 3001 estiver em uso, verifique o que a está utilizando:

• macOS/Linux: lsof -i :3001

• Windows: netstat -ano | findstr :3001

logout

Sintaxe

agentbay logout

Processo de logout

1. Tenta revogar o token de atualização no servidor.

2. Limpa os tokens de autenticação do arquivo de configuração local.

Exemplo de saída

Logging out from AgentBay...
Revoking server tokens...
Refresh token revoked successfully
Clearing local authentication data...
Successfully logged out from AgentBay

version

Sintaxe

agentbay version

Exemplo de saída

AgentBay CLI version 1.0.0
Git commit: abc1234
Build date: 2025-01-15
Environment: production
Endpoint: xiaoying-share.cn-shanghai.aliyuncs.com

Campos de saída

• Version: Número da versão da CLI.

• Git commit: Hash do commit Git no momento do build.

• Build date: Data em que a CLI foi compilada.

• Environment: Ambiente atual (produção ou pré-lançamento).

• Endpoint: Endpoint atual da API.

Estrutura do arquivo de configuração

O arquivo de configuração JSON contém:

• Token de acesso

• Token de atualização

• Token de ID

• Tipo de token

• Tempo de expiração

Gerenciamento de tokens

A CLI gerencia os tokens automaticamente:

• Renovação automática: Usa um token de atualização para obter um novo token de acesso antes que o atual expire.

• Armazenamento seguro: Armazena tokens no diretório de configuração do usuário, acessível apenas pelo usuário atual.

• Validação de token: Verifica a validade do token antes de cada chamada de API.

Variáveis de ambiente

Também é possível configurar a CLI com variáveis de ambiente:

• AGENTBAY_ENV: Ambiente de execução. Valores válidos: prod (ambiente de produção), pre (ambiente de pré-lançamento) e international (site internacional).

• AGENTBAY_CLI_ENDPOINT: Variável opcional para substituir o endpoint padrão da API.

Autenticação

P: O que devo fazer se receber um erro de "porta já em uso" ao fazer login?

R: Esse erro indica que outro programa está usando a porta 3001. Para resolver:

1. Feche o programa que está usando a porta.

2. Use lsof -i :3001 (macOS/Linux) ou netstat -ano | findstr :3001 (Windows) para encontrar o processo.

3. Encerre o processo e tente novamente.

P: E se o navegador não abrir automaticamente para autenticação?

R: A CLI exibe a URL de autenticação. Copie e cole a URL no seu navegador para concluir a autenticação.

P: O que acontece se o processo de login atingir o tempo limite?

R: A autenticação expira após 5 minutos. Se isso ocorrer, execute agentbay login novamente.

P: Como verifico meu status de login atual?

R: Execute qualquer comando que exija autenticação, como agentbay image list. Se você não estiver logado ou sua sessão tiver expirado, a CLI solicitará que faça login.

Imagens

P: Como visualizo as imagens base disponíveis?

R: Use agentbay image list --system-only para ver todas as imagens de sistema que podem ser usadas como imagens base.

P: O que devo fazer se o build da minha imagem falhar?

R: Verifique os seguintes pontos:

1. Confira se a sintaxe do Dockerfile está correta.

2. Certifique-se de que o ID da imagem base fornecido é válido.

3. Confirme que você não modificou as linhas de cabeçalho definidas pelo sistema no início do Dockerfile.

4. Use a opção -v para visualizar logs de erro detalhados.

5. Baixe um modelo executando agentbay image init -i <system-image-id>. Você pode encontrar IDs de imagens de sistema executando agentbay image list --system-only.

P: Quais partes do Dockerfile não podem ser modificadas?

R: Em um modelo de Dockerfile baixado com agentbay image init, as primeiras N linhas são definidas pelo sistema e não podem ser alteradas. Após o sucesso do comando, a saída especifica N:

[IMPORTANT] The first 5 line(s) of the Dockerfile are system-defined and cannot be modified.
[IMPORTANT] Please only modify content after line 5.

Modifique o conteúdo apenas após a linha N. Alterar essas N linhas iniciais pode causar falha no build da imagem.

P: Como verifico o status do build da imagem?

R: Execute agentbay image list para verificar o status do build. Para ver o status completo da imagem e dos recursos, use agentbay image status <image-id>.

P: Quanto tempo leva para ativar uma imagem?

R: A ativação geralmente leva de 1 a 2 minutos. A CLI exibe atualizações de progresso.

P: Posso ativar várias imagens ao mesmo tempo?

R: Sim. Cada imagem é gerenciada independentemente, então você pode ativar múltiplas imagens simultaneamente sem conflitos.

P: Os dados são perdidos quando uma imagem é desativada?

R: Não. Desativar uma imagem libera seus recursos computacionais associados, mas a imagem em si não é excluída e pode ser reativada.

Uso de comandos

P: Como obtenho ajuda sobre um comando?

R: Use a opção --help ou -h com qualquer comando ou subcomando para ver suas opções e uso:

agentbay --help
agentbay image --help
agentbay image create --help

P: Como habilito logs detalhados?

R: Use a opção -v ou --verbose com um subcomando para obter uma saída mais detalhada:

agentbay -v image create my-app -f ./Dockerfile -i code-space-debian-12

P: Onde fica localizado o arquivo de configuração?

R:

• macOS/Linux: ~/.config/agentbay/config.json

• Windows: %APPDATA%\agentbay\config.json

P: Como redefino minha configuração?

R: Exclua o arquivo de configuração e faça login novamente:

# macOS/Linux
rm ~/.config/agentbay/config.json

# Windows
del %APPDATA%\agentbay\config.json

Tratamento de erros

P: O que devo fazer se encontrar um erro com "Request ID"?

R: Se uma mensagem de erro incluir um Request ID, salve esse ID e forneça-o ao entrar em contato com o suporte técnico.

P: O que devo fazer se tiver problemas de conectividade de rede?

R: Verifique os seguintes pontos:

1. Verifique se sua conexão com a internet está funcionando.

2. Confira se o firewall não está bloqueando a conexão.

3. Verifique se é possível alcançar o endpoint do serviço AgentBay.

Visão geral

O AgentBay CLI permite alternar entre ambientes de produção e pré-lançamento. Este recurso destina-se principalmente a desenvolvimento e testes internos.

Ambientes

• Ambiente de produção (production): Ambiente padrão para uso oficial.

• Ambiente de pré-lançamento (prerelease): Destinado a testes e validações.

• Ambiente do site internacional (international): Permite acessar serviços do site internacional.

Métodos de alternância

AGENTBAY_ENV=prerelease agentbay login

# macOS/Linux
export AGENTBAY_ENV=prerelease
agentbay login
agentbay image list

# Windows (PowerShell)
$env:AGENTBAY_ENV="prerelease"
agentbay login
agentbay image list

# macOS/Linux - Add to ~/.zshrc or ~/.bashrc
echo 'export AGENTBAY_ENV=prerelease' >> ~/.zshrc
source ~/.zshrc

# Windows - Add to your system environment variables

Retornar para produção

# Unset the environment variable
unset AGENTBAY_ENV

# Or explicitly set it to the production environment
export AGENTBAY_ENV=production

Verificar o ambiente atual

Execute agentbay version para verificar o ambiente atual:

agentbay version

O campo Environment na saída indica o ambiente atual.

Usar o site internacional

Para usar o site internacional em regiões fora da China, defina o ambiente como international.

Variáveis de ambiente

• AGENTBAY_ENV=international: Usa o site internacional.

• Substituição opcional: AGENTBAY_CLI_ENDPOINT.

Exemplo (para a sessão atual)

# macOS/Linux
export AGENTBAY_ENV=international
agentbay login
agentbay image list

# Windows (PowerShell)
$env:AGENTBAY_ENV="international"
agentbay login
agentbay image list

Após definir a variável, execute agentbay version para confirmar o ambiente e o endpoint atuais.

Valores de ambiente suportados

• Ambiente de produção: production, prod ou não definido (padrão).

• Ambiente de pré-lançamento: prerelease, pre ou staging.

• Site internacional: international.

Observações

Referência de configuração de recursos

O comando image activate permite personalizar configurações de recursos com os parâmetros --cpu e --memory. Ambos os parâmetros aceitam valores inteiros.

Combinações suportadas de vCPU e memória: