No Agent Studio, é possível projetar e iterar seus comandos e comparar resultados de diferentes configurações e modelos. Depois de concluir a engenharia do comando, é possível implantá-lo como um aplicativo da Web para compartilhar com seus colaboradores ou usuários-alvo para que eles testem o aplicativo da Web. O aplicativo da Web é hospedado no Cloud Run e está disponível fora do console do Google Cloud .
Neste guia de início rápido, você fará as ações a seguir:
- Criar um comando com variáveis
- Implantar o comando como um aplicativo da Web
- Monitorar o progresso da implantação e testar o aplicativo implantado
- Atualizar e reimplantar o comando
- Testar o envio de comandos com suporte multimodal
Antes de começar
Se você nunca usou o Agent Studio, siga outro guia de início rápido ou faça o curso do Google Cloud Skills Boost para aprender os conceitos básicos do Agent Studio. Neste guia, você precisa ter o seguinte:
- Um projeto na nuvem do Google Cloud com o faturamento e a API Agent Platform ativados.
- Os papéis necessários para implantar um comando do Agent Studio como um aplicativo da Web. Se você criou um projeto para este guia, já tem as permissões necessárias.
Se quiser, você também pode garantir que a conta de serviço padrão do Compute Engine tenha os papéis necessários para a conta de serviço de implantação. Se você tiver permissão para conceder papéis, poderá conceder esses papéis ao implantar o aplicativo.
Funções exigidas
Para receber as permissões necessárias para implantar um comando do Agent Studio como um aplicativo da Web, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:
- Usuário da Agent Platform (
roles/aiplatform.user) -
Ative as APIs necessárias:
Administrador do Service Usage (
roles/serviceusage.serviceUsageAdmin) -
Conceda os papéis necessários à conta de serviço padrão do Compute Engine:
Administrador do IAM do projeto (
roles/resourcemanager.projectIamAdmin) -
Implantar um aplicativo do Cloud Run:
- Administrador do Cloud Run (
roles/run.admin) - Desenvolvedor de origem do Cloud Run (
roles/run.sourceDeveloper)
- Administrador do Cloud Run (
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.
Papéis necessários para a conta de serviço de implantação
Para garantir que a conta de serviço padrão do Compute Engine tenha as permissões necessárias para executar builds em seu nome, peça ao administrador para conceder os seguintes papéis do IAM à conta de serviço padrão do Compute Engine no projeto:
- Agente de serviço da Vertex AI (
roles/aiplatform.serviceAgent) - Conta de serviço do Cloud Build (
roles/cloudbuild.builds.builder)
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
O administrador também pode conceder à conta de serviço padrão do Compute Engine as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.
Se você tiver permissão para conceder papéis, poderá conceder esses papéis ao implantar o aplicativo.
Criar um comando com variáveis
Acesse a página de criação de comandos do Agent Studio e clique em Adicionar variável na caixa de entrada de comandos.
Na caixa de diálogo Gerenciar variáveis de comando, insira um nome de variável e atribua um valor a ela. Em seguida, clique em Aplicar.
Na caixa de entrada do comando, escreva o comando usando a variável e ajuste outros parâmetros. Por exemplo, é possível ativar o embasamento com a Pesquisa Google e definir "Sempre buscar o clima atual na Web" como as instruções do sistema.
Implantar o comando como um aplicativo da Web
Para implantar o comando como um aplicativo da Web, clique em e em Implantar como app.
Salve o comando
A caixa de diálogo para salvar o comando vai aparecer, já que é necessário salvar antes de implantar. A caixa de diálogo de implantação será aberta automaticamente depois que o comando for salvo.
Ativar APIs para a primeira implantação e conceder permissões
- Depois que o comando for salvo, o processo de implantação vai continuar. Se esta for sua primeira implantação, uma caixa de diálogo vai aparecer para ativar as APIs necessárias. Clique em Ativar APIs necessárias.
-
Depois que as APIs forem ativadas, a caixa de diálogo Criar um app da Web vai aparecer. É possível escolher
Exigir autenticação (via Identity-Aware Proxy) ou Permitir acesso público.
- Se a autenticação obrigatória for escolhida, siga o guia para conceder acesso (incluindo você).
- Ao selecionar Permitir acesso público, qualquer pessoa poderá acessar o app. Portanto, não inclua informações sensíveis ou informações de identificação pessoal (PII) no comando. Marque a caixa de seleção Entendo que esse app será implantado publicamente para confirmar.
- Clique em Criar app para iniciar a implantação.
- Se esta for sua primeira implantação, outra caixa de diálogo vai aparecer pedindo que você conceda os papéis necessários à conta de serviço. Clique em Conceder tudo para continuar.
Início da implantação
O Agent Studio vai criar um arquivo ZIP com o código-fonte do aplicativo da Web e fazer upload dele para um bucket do Cloud Storage. Depois que a implantação começar, a caixa de diálogo Gerenciar app da Web vai aparecer com informações sobre a implantação, como o nome do aplicativo, quando ele foi implantado pela última vez, o status da implantação e muito mais.
Como monitorar o status da implantação
A implantação leva de 2 a 3 minutos para ser concluída, e o status é mostrado na coluna Status da caixa de diálogo Gerenciar app da Web. Se você fechar a caixa de diálogo Gerenciar app da Web, poderá reabri-la no menu abaixo do botão Criar com código.
Quando a implantação for concluída, a coluna de status vai mudar para Pronto, e o botão Abrir vai aparecer ao lado do nome do aplicativo.
Controle de acesso e chave secreta
Seu aplicativo da Web é implantado com o controle de acesso Permitir não autenticado ativado por padrão. Para desativar, clique no botão de ícone de lápis . Consulte a seção sobre como desativar o acesso público para mais informações.
Para oferecer proteção básica, o aplicativo da Web exige que uma chave secreta seja adicionada ao final do URL para enviar o comando. A chave secreta está na coluna Chave secreta. Se você abrir o aplicativo da Web no Agent Studio, a chave será adicionada ao final do URL automaticamente.
Abra o aplicativo da Web e envie o comando
Clique em Abrir na caixa de diálogo Gerenciar app da Web para acessar o aplicativo
implantado. O aplicativo deve ser aberto com a chave secreta adicionada ao final do URL no formato ?key=SECRET_KEY.
Insira um valor para a variável e clique em Enviar. Os resultados vão aparecer à direita.
Abra o aplicativo da Web no menu do botão "Criar com código"
Se o aplicativo da Web estiver pronto, você também poderá abri-lo no menu do botão Criar com código.
O Cloud Run é um serviço sem servidor, o que significa que o contêiner do aplicativo será encerrado se não estiver sendo usado ativamente. Portanto, o aplicativo da Web pode levar alguns segundos para carregar ou um envio não funcionará se você deixar o aplicativo da Web inativo por muito tempo. Atualize a página para resolver o problema.
Monitorar o status no sininho de notificação
Também é possível monitorar o status no menu Notificações clicando no ícone de sino. O ícone de sino vai parar a animação de carregamento e mostrar um círculo verde se a implantação for concluída com sucesso.
Se você clicar na notificação, será redirecionado para a página do Cloud Run. O URL na página do Cloud Run não tem a chave secreta
anexada. Você vai precisar anexá-lo manualmente no formato ?key=SECRET_KEY.
Atualizar e implantar novamente o comando
Você pode editar ainda mais seu comando no Agent Studio e transformá-lo em uma conversa. Em seguida, clique no botão Criar com código e em Gerenciar app para abrir a caixa de diálogo Gerenciar app da Web. Clique em Atualizar app para reimplantar o aplicativo da Web com o comando atualizado.
Uma caixa de confirmação é exibida. Ele informa que, se você reimplantar, vai perder as mudanças feitas no aplicativo da Web implantado fora do Agent Studio (como no editor de código-fonte do Cloud Run). Clique em Confirmar para continuar.
A caixa de diálogo Gerenciar app da Web vai aparecer de novo. O processo é semelhante à implantação inicial. É possível monitorar o progresso da mesma forma que na primeira implantação.
Depois que a atualização for concluída, você poderá abrir o aplicativo da Web novamente. Você vai ver a UI de conversa com a variável de comando. Preencha o valor e digite qualquer conteúdo não vazio para continuar a conversa.
Inserir conteúdo multimodal
É possível inserir entradas como imagens, vídeos, áudios e documentos na UI de conversação. As entradas aceitas dependem do modelo selecionado para o comando. Consulte a documentação sobre suporte multimodal para cada modelo.
Para inserir um arquivo, clique no botão de ícone de clipe na caixa de entrada da conversa.
Você poderá interagir com o modelo usando a entrada que fornecer.
Tópicos avançados
Depois de se familiarizar com o processo de implantação, considere as ações a seguir.
Editar código-fonte no Cloud Run
Se você quiser personalizar o aplicativo da Web, faça alterações no
código-fonte no Cloud Run. Abra a página do código-fonte do Cloud Run
na caixa de diálogo Gerenciar app da Web clicando no botão de ícone de mais
no final da linha.
Como alternativa, você também pode acessar a página de segurança no aplicativo da Web clicando no link do editor de código-fonte.
Na página do código-fonte do Cloud Run, clique em Editar origem para iniciar o modo de edição. Quando terminar, clique em Salvar e reimplantar.
Depois que a reimplantação for concluída, abra o aplicativo no Agent Studio. Acesse a página do Agent Studio pelo link no selo Implantado na Agent Platform.
Conceder acesso
Para conceder acesso ao app a usuários ou grupos, siga estas etapas:
- Abra a caixa de diálogo Manage Web App.
- Clique no ícone de lápis na coluna Controle de acesso. A página de segurança do Cloud Run é aberta em uma nova guia.
- Na página de segurança do Cloud Run, encontre a caixa de seleção do Identity-Aware Proxy (IAP). Verifique se ela está marcada e clique em Editar política.
-
Uma subtarefa vai aparecer para você editar o acesso. Insira os e-mails de usuários ou grupos no campo Principal.
Se você for um usuário em uma organização, só poderá adicionar usuários da mesma organização.
- Deixe o campo de níveis de acesso em branco.
- Clique em Salvar.
-
Depois que a subtarefa for fechada, clique em Salvar novamente na página do Cloud Run.
Desativar o acesso público
Quando você não precisar que o aplicativo da Web seja acessível publicamente, será possível desativá-lo no Cloud Run. Abra a caixa de diálogo Gerenciar app da Web e clique no ícone de lápis na coluna Controle de acesso. A página de segurança do Cloud Run será aberta em uma nova guia.
Também é possível acessar a página de segurança no aplicativo da Web clicando no link Configurações de segurança.
Na página "Segurança" do serviço do Cloud Run correspondente ao seu aplicativo da Web, marque Usar o Cloud IAM para autenticar as solicitações recebidas e escolha Exigir autenticação. Clique em Salvar.
Isso vai fazer com que o aplicativo da Web não seja mais acessível pelo URL. Se você tentar acessá-la, vai aparecer uma página com a mensagem Erro: proibido.
Ativar o acesso público novamente
Se você quiser reativar o acesso público, desmarque a caixa de seleção Usar o Cloud IAM para autenticar as solicitações recebidas e salve. Se você escolher Permitir invocações não autenticadas, isso não vai funcionar se o projeto estiver em uma organização. Consulte Autenticação no Cloud Run para mais detalhes.
Configurar o acesso local para desenvolvimento
No acesso antecipado, o controle de acesso ainda não está disponível. Portanto, depois de desativar o acesso público, a única maneira de acessar o aplicativo da Web é configurando um proxy local. É possível fazer isso usando os comandos gcloud. Primeiro, abra o Cloud Shell pelo botão do ícone de terminal no canto superior direito do console do Google Cloud . Será preciso autorizar o Cloud Shell. Clique em Autorizar para continuar.
Quando terminar, abra a caixa de diálogo Gerenciar app da Web e clique no botão de ícone de mais
no final da linha para ver mais ações. Clique em Configurar o acesso local pelo Cloud Shell.
Um comando será adicionado ao Cloud Shell. Pressione Enter e aguarde
a conclusão da impressão. Clique no link na linha que começa com Click on the
link to preview. Você poderá ver seu aplicativo. Esse link
só funciona quando o comando gcloud está em execução.
Problemas comuns
Erro de autenticação: nenhuma chave secreta
Se o erro a seguir aparecer, significa que nenhuma chave secreta foi anexada ao
URL. Siga as instruções para abrir o aplicativo da web
no Agent Studio ou copie a chave secreta da
caixa de diálogo Gerenciar app e adicione-a ao final do URL no formato
?key=SECRET_KEY.
Erro de autenticação: chave secreta inválida
O erro a seguir significa que a chave anexada ao URL é inválida. A chave secreta é exclusiva para cada comando. Se você tiver uma chave secreta de outro prompt, ela não vai funcionar. Siga as instruções para abrir o aplicativo da Web corretamente.
400 Argumento inválido: entrada vazia
O erro a seguir acontece quando você tem entradas na variável de comando, mas o chat está vazio. Uma mensagem de erro 400 será exibida. Para corrigir isso, digite algo no campo e reenvie.
400 Argumento inválido: mimeType não é compatível
Se você escolher um tipo de arquivo que não é compatível com o modelo, ele vai retornar um erro 400. Isso é esperado, e você precisará usar outros tipos de arquivos compatíveis com o modelo. Consulte a documentação sobre suporte multimodal para cada modelo.
A seguir
Guia de início rápido do Agent Studio: enviar comandos de texto para o Gemini
Saiba como enviar comandos de texto para o Gemini usando o Agent Studio.