Documentação › Agentes de IA
Agentes de IA
Os agentes rodam nos cartões com a sua própria conta, no seu computador ou nos seus servidores. Ligados por cabos, eles fazem pedidos uns aos outros e rodam comandos nos shells que você deixar, sempre à vista.
O Octopus usa o Claude Code e o Codex que você já tem, com a sua conta (Claude Pro ou Max, ChatGPT Plus ou Pro) ou com uma chave de API. Os limites são os do seu plano, e as conversas ficam nas suas máquinas.
Passo a passo
- Abra um Novo terminal (⌘TCtrl+Shift+T) e escolha o bloco Claude Code ou Codex.
- Na primeira vez numa máquina, entre na sua conta: no seu computador, pelo navegador; num servidor, com um link e um código.
- O agente já começa sabendo que está num cartão do Octopus. Quando você fala de uma nota, de um arquivo anexado ou de outro agente, ele procura o que está ligado a ele.
- A aba do cartão mostra o estado: “· trabalhando” ou “· esperando você”. A borda fica âmbar quando ele pede você e verde quando termina.
| Novo terminal | ⌘TCtrl+Shift+T |
Cada agente pode ser visto como terminal ou como chat, com a mesma conversa.
Veja tambémChat | TerminalSkills instaladasPedindo você e Terminou
Abriu um Claude Code ou um Codex numa máquina onde ele não está instalado? O Octopus oferece instalar ali mesmo, inclusive num servidor, e abre o agente quando termina.
Passo a passo
- Crie o terminal do agente como sempre. Se ele não existir na máquina, aparece, por exemplo, “O Codex não está instalado em staging”.
- Clique em “Instalar o Codex”. Um cartão “Instalando Codex” roda o instalador oficial, sem senha, à vista.
- Depois da instalação, entre na sua conta: no seu computador, pelo navegador; num servidor, com um link e um código.
- Quando tudo termina, o cartão da instalação fecha e o agente abre.
- Prefere instalar do seu jeito? “Abrir um Shell” abre um shell na mesma pasta.
Na primeira vez que você abre o Octopus, a configuração rápida também instala o tmux, o Claude Code e o Codex no seu computador.
Veja tambémClaude Code e Codex com a sua conta
Um Claude Code ou Codex aberto fora do Octopus (num tmux antigo, ou digitado à mão num cartão Shell) roda sem alertas, sem chat e sem Maestro. Converter reabre a mesma conversa, no mesmo tmux, já com tudo isso.
Passo a passo
- Um agente de fora aparece com o selo “externo” na aba. A barra do cartão mostra o botão Converter (também no botão direito › “Converter…”).
- Clique em Converter. O aviso lista o que ele ganha: alertas quando precisar de você, o chat do Octopus, retomar a conversa depois de reiniciar, Maestro e mensagens entre agentes.
- Se ele estiver trabalhando, escolha “Converter quando ele parar” (o selo vira “converte quando parar”) ou “Converter agora”. Parado, clique em “Converter”. “Agora não” deixa como está.
- O selo mostra “convertendo…” e, no fim, um aviso confirma. A conversa, os arquivos e o tmux continuam; só o processo do agente reinicia.
- Ao trazer sessões de um servidor, “Trazer e converter” faz tudo de uma vez.
Se o agente não fechar para a conversão, o Octopus pede que você o feche (Ctrl-C) e tente de novo.
Veja tambémClicar num servidor: as sessões que já rodam
Quando o Claude Code manda uma sessão para o segundo plano, ela continua falando com o Octopus: usa as notas e os cartões ligados e avisa quando precisa de você.
Passo a passo
- No Claude Code, mande a sessão para o segundo plano como de costume (por exemplo, com /background).
- Ela continua com o octo: lê as notas ligadas, fala com os outros agentes e manda os avisos ao Octopus.
- No chat, o que roda em segundo plano aparece na caixa acima da mensagem.
Enquanto um trabalho seu roda por trás (testes, uma rodada longa), o cartão continua com o indicador de trabalho; o aviso “Terminou” só sai quando tudo acaba.
Veja tambémWorkflow e agentes em segundo planoTrabalho por trás e Quem decide
Ligue dois cartões com um cabo e os agentes passam a trocar pedidos e respostas, mesmo em máquinas diferentes. Um Claude Code no seu computador pode pedir um treino ao Codex no gpu-01 e esperar o resultado.
Passo a passo
- Escolha um cartão, aperte ⌘LCtrl+Shift+L (ou o botão Conectar da barra) e clique no outro cartão. O cabo aparece.
- Peça ao seu agente com palavras comuns: “pergunte ao Codex se os testes passam”. Ele usa o octo ask e espera a resposta.
- No outro cartão chega uma mensagem que começa com “[Octopus] Pedido de” e traz o número do pedido. O agente faz o trabalho e responde com o octo reply; a resposta volta para quem perguntou.
- Para acompanhar sem interromper, o agente usa o octo check e vê a tela atual do outro.
- Num chat, essas mensagens aparecem como “Mensagem de outro agente pelo Octopus”.
| Iniciar conexão | ⌘LCtrl+Shift+L |
Mensagens longas chegam inteiras, e cada pedido tem um número: a resposta sempre acha quem perguntou. Se a resposta demora mais que a espera, ela chega depois, como “[Octopus] Resposta de”.
Veja tambémocto ask, check e replyComandos num shell ligadoTentáculos (cabos)
Um agente ligado a um shell roda comandos nele com o octo run. O comando aparece digitado no cartão, na pasta e com as variáveis daquele shell, e a saída inteira e o código de saída voltam para o agente.
Passo a passo
- Ligue o agente a um cartão Shell, ou use “Shell ao lado”.
- Peça a tarefa: “veja os logs da API no staging”. O agente roda o octo run no shell e você vê o comando ser digitado ali.
- O octo run espera o comando terminar e devolve a saída e o código de saída. Se ele passa do tempo, continua rodando e o agente acompanha com o octo run --wait.
- Para responder a uma pergunta do programa (um [y/N]) ou interromper, o agente manda teclas com o octo keys, como y, Enter ou C-c.
- Com o octo run --fora, o comando roda por fora do cartão, sem aparecer nem atrapalhar o que está no shell. Serve para leituras rápidas: status, logs, espaço em disco.
- Com o octo copy, o agente copia arquivos e pastas entre as máquinas dos shells ligados a ele, direto de servidor a servidor quando um alcança o outro.
O agente nunca digita senhas por você: se um comando pedir senha, ele pede para você digitar no cartão.
Veja tambémA trava “Comandos de agentes”octo run, keys e copyShell ao lado
Cada cartão Shell tem a sua trava: Livre, Perguntar ou Bloqueado. Ela decide se os agentes ligados rodam comandos, teclas e cópias ali sem perguntar, só com a sua aprovação, ou nunca.
Passo a passo
- Clique com o botão direito num cartão Shell e abra “Comandos de agentes”.
- “Livre”: os agentes ligados rodam comandos ali sem perguntar. “Perguntar”: cada comando espera você permitir. “Bloqueado”: nenhum comando de agente roda ali.
- Nos servidores marcados como “Servidor de produção” (folha do servidor, em Avançado), os shells começam em “Perguntar”.
- O agente vê a trava de cada shell no octo list. Uma recusa vale para aquele comando: ele não insiste e pergunta a você na conversa.
A trava vale para o octo run, o octo keys e o octo copy. Trocar a trava desfaz as liberações “nesta sessão” daquele shell.
Veja tambémAprovar um comandoCadastrar um servidor
Com a trava em “Perguntar”, o pedido do agente aparece numa folha: quem pede, em qual shell e máquina, e o comando inteiro. Você permite uma vez, permite nesta sessão ou recusa.
Passo a passo
- Quando um agente pede, a folha abre e o cartão dele fica âmbar, com o motivo “Pediu para rodar em” e o nome do shell.
- Leia o comando. A linha de cima diz a máquina e o tipo do pedido: no cartão, por fora do cartão, teclas ou cópia de arquivo.
- “Permitir” (↩Enter) roda só este comando. “Permitir nesta sessão” libera este agente neste shell até o Octopus fechar. “Recusar” (Esc) não roda nada.
- Sem resposta em até 90 segundos, o pedido vale como recusado e o agente fica sabendo.
| Permitir | ↩Enter |
| Recusar | Esc |
Os pedidos aparecem um de cada vez: enquanto um espera a sua resposta, os outros aguardam na fila.
Veja tambémA trava “Comandos de agentes”Pedindo você e Terminou
No menu de um cartão de agente, “Copiar ID da sessão” copia o identificador da conversa, para retomá-la em outro lugar. “Copiar diagnóstico dos alertas” copia o que o cartão recebeu e decidiu sobre alertas e “rodando”.
Passo a passo
- Clique com o botão direito no cartão do Claude Code ou do Codex.
- “Copiar ID da sessão”: um aviso mostra o ID copiado (passe o mouse no item para vê-lo antes). Se o agente ainda não salvou a conversa, o Octopus avisa.
- “Copiar diagnóstico dos alertas” (desde a 1.0.16): cole numa conversa para explicar um alerta que não veio ou veio fora de hora.
No chat, o ID também aparece no painel do anel de contexto, em “Sessão”, com “Copiar”.
Veja tambémContexto e limites do planoCopiar diagnóstico dos alertas
Em cada máquina onde abre terminais, o Octopus instala duas skills para o Claude Code e o Codex: “octopus”, que ensina o agente a usar o canvas, e “octopus-maestro”, para quando ele é o Maestro.
Passo a passo
- Elas ficam em ~/.claude/skills e ~/.codex/skills, no seu computador e em cada servidor, junto com o comando octo. O Octopus mantém tudo atualizado.
- A skill octopus entra em ação quando você fala de algo ligado ao cartão: uma nota, uma imagem anexada, outro agente, um shell, um portal, uma conta na nuvem ou um desenho.
- A skill octopus-maestro só vale para um agente em modo Maestro: decidir se divide o trabalho, recrutar, acompanhar e fechar o time.
- Ao abrir um agente, o Octopus também avisa a ele, logo no começo, que ele está num cartão do canvas.
Num servidor com mais de um perfil do Claude Code (CLAUDE_CONFIG_DIR nas variáveis do servidor), a skill vai para cada perfil.
Veja tambémAs skills octopus e octopus-maestroO que é o Maestro