No Agent Studio, é possível criar e iterar 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. 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 de comando
- Implantar seu 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.
- As funções necessárias 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, verifique se a conta de serviço padrão do Compute Engine tem os papéis necessários para a conta de serviço de implantação. Se você tiver permissão para conceder papéis, poderá fazer isso 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) -
Implante 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 seu projeto:
- Agente de serviço da Agent Platform (
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 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
Navegue até 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 e atribua um valor à variável. Em seguida, clique em Aplicar.
Na caixa de entrada do comando, crie o comando usando a variável e ajuste outros parâmetros. Por exemplo, você pode ativar o Fundamentação com a Pesquisa Google e definir "Sempre receber a previsão do tempo atual da Web" como instruções do sistema.
Implantar seu comando como um aplicativo da Web
Para implantar seu comando como um aplicativo da Web, clique em e depois em Implantar como app.
Salve o comando
A caixa de diálogo de solicitação de salvamento vai aparecer, já que é necessário salvar antes de implantar um comando. A caixa de diálogo de implantação vai abrir 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 obrigatórias.
-
Depois que as APIs forem ativadas, a caixa de diálogo Criar um app da Web vai aparecer. Você pode 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 pode acessar o app. Portanto, não inclua informações de identificação pessoal (PII) sensíveis 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.
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
O aplicativo da Web é implantado com o controle de acesso Permitir não autenticado ativado por padrão. Para desativar, clique no botão com o í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 uma chave secreta que precisa ser adicionada ao 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 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á desativado se não estiver sendo usado ativamente. Por isso, o aplicativo da Web pode levar alguns segundos para carregar, ou um envio não vai funcionar se você deixar o aplicativo da Web inativo por muito tempo. Atualizar a página deve resolver esse problema.
Monitorar o status no sininho de notificação
Você também pode 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, ela vai redirecionar você para a página do Cloud Run. O URL na página do Cloud Run não tem a chave secreta
anexada. É necessário anexar manualmente no formato ?key=SECRET_KEY.
Atualizar e reimplantar o comando
Você pode editar ainda mais o 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 seu aplicativo da Web com o comando atualizado.
Uma caixa de confirmação é exibida. Ele informa que, se você reimplantar, vai perder todas 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 a primeira implantação.
Depois que a atualização for concluída, você poderá abrir o aplicativo da Web novamente. A UI de conversa com a variável de comando vai aparecer. Preencha o valor e digite qualquer conteúdo não vazio para continuar a conversa.
Inserir conteúdo multimodal
Você pode inserir entradas como imagens, vídeos, áudios e documentos na UI de conversa. 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 fornecida.
Tópicos avançados
Depois de se familiarizar com o processo de implantação, considere as seguintes ações.
Editar código-fonte no Cloud Run
Se quiser personalizar o aplicativo da Web, faça mudanças 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
mais no final da linha.
Como alternativa, acesse a página de segurança no aplicativo da Web clicando no link Editor de código-fonte.
Na página do código-fonte do Cloud Run, clique em Editar fonte para iniciar o modo de edição. Quando terminar, clique em Salvar e implantar novamente.
Depois que a nova implantação for concluída, abra o aplicativo no Agent Studio. Você pode acessar a página do Agent Studio pelo link no selo Implantado na plataforma de agentes.
Conceder acesso
Para conceder acesso ao app a usuários ou grupos, siga estas etapas:
- Abra a caixa de diálogo Gerenciar app da Web.
- 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 concluída, clique em Salvar novamente na página do Cloud Run.
Desativar o acesso público
Quando não for necessário que o aplicativo da Web seja acessível publicamente, é 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.
Você também pode 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 fará com que o aplicativo da Web não possa mais ser acessado pelo URL. Se você tentar acessar, vai aparecer uma página Erro: proibido.
Ativar o acesso público de novo
Se 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 a opção Permitir invocações não autenticadas, ela 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 comandos gcloud. Primeiro, abra o Cloud Shell clicando no botão do ícone do terminal no canto superior direito do console do Google Cloud . Ele vai pedir que você autorize 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
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. Sua inscrição vai aparecer. Esse link
só funciona quando o comando gcloud está em execução.
Problemas comuns
Erro de autenticação: nenhuma chave secreta
Se o seguinte erro 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 ao 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 comando, ela não vai funcionar. Siga as instruções para abrir o aplicativo da Web corretamente.
400 Argumento inválido: entrada vazia
O seguinte erro ocorre quando você tem entradas na variável de solicitação, mas o chat está vazio. Uma mensagem de erro 400 vai aparecer. Para corrigir isso, digite algo que não esteja vazio e reenvie.
400 Argumento inválido: mimeType não é compatível
Se você escolher um tipo de arquivo que o modelo não aceita, 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: envie comandos de texto para o Gemini
Saiba como enviar comandos de texto para o Gemini usando o Agent Studio.