Criar um projeto

Sintaxe do comando

Use o seguinte comando para estruturar um novo projeto:

agentengine create [--template <template-id>] [--name <display-name>] [--dir <path>] [--llm <provider>] [--llm-base-url <url>] [--llm-model <model>] [--llm-auth-header <header>] [--memory] [--yes]

Dependendo dos sinalizadores especificados, a CLI solicita que você configure seu projeto.

Esse comando cria um diretório de projeto que contém um arquivo project-config.yaml e estrutura o diretório de espaço de trabalho do seu agente em um subdiretório <project-directory>/agents/<slug>. O valor <slug> é uma versão em minúsculas e hifenizada do valor --name. O diretório do espaço de trabalho contém agent.yaml, .env e os outros arquivos específicos do agente descritos em seções futuras.

Sinalizadores de comando

Restrições de nome de exibição

A CLI copia o nome de exibição nos arquivos de origem gerados. O nome não pode conter os seguintes caracteres:

• Aspas duplas (")

• Barras invertidas (\)

• Backtiques

• Caracteres de controle, quebra de linha ou direção de texto

Se você inserir um nome inválido ao usar a CLI interativa, a CLI exibirá um erro e solicitará novamente. Se você passar um nome inválido para o sinalizador --name, o comando falhará com um erro que nomeia o caractere não permitido ou a categoria de caracteres.

Modelos suportados

A tabela a seguir descreve os modelos iniciais que você pode passar para o comando agentengine create:

Padrões do ambiente local

Quando você escolhe uma conexão LLM no catálogo do provedor, agentengine create solicita os detalhes da conexão necessária, como uma chave de API. Se LLM_API_KEY estiver configurado em seu ambiente de shell, o comando o oferecerá como padrão. Quando você confirma o valor, o comando o grava no arquivo .env gerado como LLM_API_KEY. Você não precisa configurar este valor manualmente.

Quando a memória está ativada, o agentengine create detecta o VOYAGE_API_KEY do seu ambiente local e o oferece como padrão. Confirmar o valor grava no .env gerado.

Quando você executa agentengine create com o sinalizador --yes, o comando não solicita valores de ambiente detectados. Para cada opção do catálogo do fornecedor exceto custom, você deve definir LLM_API_KEY em seu ambiente antes de executar o comando. Quando você também passar --memory --yes, deverá definir VOYAGE_API_KEY em seu ambiente antes de executar o comando, ou o comando falhará.

O modelo chatbot-client gera um arquivo .env.local em vez de um arquivo .env. Antes de executar o aplicativo, você deve preencher manualmente o arquivo .env.local com os seguintes valores:

• URL da API do seu agente implementado

• IDdo projeto

• ID doseu workspace

• Seu token de acesso à conta de serviço

Personalize seu agente com andaime

Após a conclusão de agentengine create, navegue até o diretório do espaço de trabalho do seu agente em <project-directory>/agents/<slug> e revise os arquivos gerados.

Todos os agentes gerados incluem a habilidade atlas-agent-engine em .agents/skills/atlas-agent-engine (para Codex, Copiot e outros agentes) ou .claude/skills/atlas-agent-engine (para laudo código).

Ao usar um modelo de início de agente , revise a origem do agente gerada e o arquivo .env para confirmar se a conexão LLM atende aos seus requisitos. O cliente LLM, o modelo, o endpoint e o comportamento de autenticação são configurados no código-fonte do agente gerado.

Para opções de catálogo que configuram uma conexão LLM, o arquivo .env gerado contém a credencial compartilhada como LLM_API_KEY. Se você escolher Manual setup, configure a conexão LLM no código do agente e adicione quaisquer segredos que o código exija ao arquivo .env. Para saber mais, consulte Configurar um gateway LLM no código.

Ao usar o modelo chatbot-client, revise o arquivo .env.local e confirme se você definiu corretamente a URL da API, a ID do projeto, a ID do espaço de trabalho e o token de acesso à conta de serviço do agente implantado. Não há nenhum arquivo agent.yaml em um aplicativo cliente de chatbot.

Configurar um Gateway LLM a partir de um Modelo Inicial

Ao executar o comando agentengine create, o comando solicita que você escolha uma conexão LLM, semelhante ao exemplo a seguir:

Which LLM connection do you want to use?
  1) OpenAI
  2) Anthropic
  3) Google Gemini
  4) OpenRouter
  5) OpenAI-compatible - AWS Bedrock, Azure Foundry
  6) Anthropic-compatible - AWS Bedrock, Azure Foundry
  7) Manual setup - implement the LLM client in code

Se você escolher um fornecedor deste catálogo, o comando agentengine create solicitará os detalhes exigidos pela conexão, que poderão incluir o seguinte:

• URL base

• Nome do modelo ou sistema

• Chave API

• Cabeçalho de autenticação para conexões quando o host não é reconhecido

O comando grava o cliente LLM selecionado na origem do agente gerada e armazena a credencial compartilhada no arquivo .env gerado como LLM_API_KEY.

O comando também solicita que você escolha como o Agente e a Ferramenta acessam hosts externos:

• Aplique a configuração network.egress recomendada. Se nenhum host de gateway estiver disponível, como quando você escolhe Manual setup (custom), essa opção instrui você a configurar a saída do LLM posteriormente.

• Permitir todo o acesso de saída.

Se sua conexão LLM não for uma das opções listadas, escolha Manual setup e configure o gateway no código. Esta opção cria um stub de construtor de modelo para que você possa configurar a conexão no código do agente .

Configurar um Gateway LLM no Código

Para conectar um LLM ao seu agente, crie um modelo específico da framework e passe a instância do modelo resultante para o método app.llm(...) a partir do ponto de entrada do seu agente. Você pode colocar o código de construção de modelo em qualquer arquivo em seu código de agente , mas os modelos iniciais colocam um stub em um arquivo específico do idioma. Se você não usar um modelo inicial, poderá definir o modelo em outro lugar, desde que app.llm(...) receba um objeto de modelo compatível.

A tabela a seguir descreve as convenções para configurar um gateway LLM no código em diferentes tempos de execução:

O construtor é o que define o endpoint, cabeçalhos de autenticação e nome do modelo. Por exemplo, o modelo LangGraph Python insurance-agent define build_llm() em src/<module>/llm.py e retorna um LangChain BaseChatModel. O ponto de entrada do agente importa build_llm() e passa o modelo retornado para app.llm(...).

Permita o host do gateway para que seu agente possa acessá-lo. Adicione o host do gateway personalizado e a porta ao bloco network.egress no arquivo agent.yaml. Por exemplo, para adicionar gateway.example.com:443 à lista de permissões de saída existente da sandbox de ferramenta, execute o seguinte comando:

agentengine agent egress add --component tool gateway.example.com:443

Para saber mais sobre como configurar a saída de rede para seu agente, consulte o guia Introdução à saída de rede.

Sintaxe do comando

No diretório do espaço de trabalho do agente , execute o seguinte comando para registrar o agente e gerar arquivos locais:

agentengine init [--workspace-id <id>] [--project-id <id>] [--org-id <id>] [--base-url <url>] [--context <name>]

Este comando seleciona ou cria interativamente uma organização e projeto, gera arquivos de desenvolvimento local e registra seu agente como um espaço de trabalho no Atlas Agent Engine.

Sinalizadores de comando

Fluxo interativo

Quando você executa o agentengine init, a CLI orienta você nas seguintes etapas:

1. Lista suas organizações com um menu numerado, incluindo uma opção "Create a new organization...". Se não existirem organizações, a CLI solicitará que você insira um nome para criar uma.

2. Lista seus projetos com um menu numerado depois que você escolhe uma organização, incluindo uma opção "Create a new project...". Se não existir nenhum projeto, a CLI solicitará que você insira um nome para criar um.

3. Salva o projeto selecionado como seu project_id ativo no estado de autenticação local.

4. Gera os seguintes arquivos dev locais em seu diretório de agente :

   • docker-compose.yml

   • .agentengine/Dockerfile

   • .agentengine/entrypoint.py

   • .dockerignore

   • .gitignore

5. Registra o agente como um espaço de trabalho na plataforma e cria o arquivo .agentengine/state.json com o workspace_id, org_id e project_id especificado.

Modelos para agentes iniciais

Se você estiver usando um modelo TypeScript, instale as dependências do Node.js antes de iniciar seu agente localmente:

pnpm install

Depois de revisar seu agente com andaime, execute agentengine dev up para iniciar seu agente localmente:

agentengine dev up

Modelo de cliente do chatbot

Após definir os valores necessários no arquivo .env.local, instale as dependências e inicie o servidor de desenvolvimento:

pnpm install
pnpm run dev

Abra o http://localhost:3000 no seu navegador para usar a interface do usuário de bate-papo.