O modelo de agentes

O que é um agente?

Um agente é um ator nomeado, com uma persona, um conjunto de skills e um adaptador no qual rodar. Os agentes são atores de pleno direito, no mesmo sentido que os humanos: eles escrevem mensagens, são donos de tickets, deixam revisões e aparecem na mesma lista. São eles que fazem o trabalho.

Todo agente pertence a exatamente um espaço de trabalho. Esse é um invariante rígido — agent.workspaceId nunca é nulo, é o próprio espaço de trabalho do agente que determina em qual arquivo de banco de dados suas linhas serão gravadas, e criar um agente sem espaço de trabalho é recusado.

Um agente também é um diretório. Sua definição fica em agents/<slug>/AGENTS.md, dentro do diretório de dados do espaço de trabalho, com as skills que ele possui vinculadas por symlink em agents/<slug>/.agents/skills. A linha no banco de dados e o arquivo são gravados juntos. A semeadura é idempotente: se a linha do agente já existir, os arquivos em disco e os links de skills ainda assim são regravados. O chamador de produção é a criação do espaço de trabalho, e não cada inicialização do servidor.

O que um agente carrega

Atributo	O que faz
`name`	Identificador curto no estilo slug (`architect`, `qa`). É também aquilo contra o que os `@mentions` são resolvidos
`title`	Cargo legível por humanos
`persona`	Instruções livres de personalidade e comportamento, injetadas como uma seção do prompt
`systemPrompt`	Instruções extras opcionais, injetadas como uma seção “Agent instructions” — elas não substituem o restante do prompt montado
`skills`	Conjunto de nomes de skills sem distinção entre maiúsculas e minúsculas, espelhado como links de skills em disco
`adapterId`	Qual executor o agente aciona. Nulo recorre ao loop integrado
`modelId`	Qual modelo dentro desse adaptador
`effort`	Nível de raciocínio, retirado do próprio vocabulário do modelo selecionado
`contextSize`	Substituição da janela de contexto
`silenceTimeoutMinutes`	Substituição por agente (1–240) para o watchdog de silêncio
`reportsTo`	Id do agente pai — a cadeia de reporte que o organograma desenha

Você edita todos esses campos em Configurações → Espaço de trabalho → Agentes. Novo agente cria um agente sem nome que você preenche em seguida.

Skills

As skills são nomes sem distinção entre maiúsculas e minúsculas na entidade agente. Duas coisas distintas acontecem com elas:

Os nomes são listados no prompt montado sob um título “Skills”. É só isso o que o conjunto da entidade faz sozinho — não existe uma biblioteca de prompts por skill associada a ele.
O diretório de cada skill nomeada (skills/<slug>/SKILL.md no espaço de trabalho) é vinculado à própria pasta do agente. No harness integrado, o frontmatter das skills vinculadas é carregado automaticamente no prompt de sistema e o agente lê um corpo sob demanda; digitar /skill:<name> em uma conversa carrega esse corpo como uma diretiva para o turno.

As skills buscadas de fora passam por uma varredura fail-closed da cadeia de suprimentos entre a busca e a gravação — nenhum conteúdo de skill chega ao disco ou a um prompt sem um veredito. O “fora” são repositórios do GitHub que você mesmo registra como fontes de skills: não existe uma loja curada, então os próprios metadados do repositório (a descrição, as estrelas, o nome da skill) são dados de exibição não confiáveis e o veredito da varredura é o único sinal de segurança. Uma instalação busca o diretório inteiro da skill, o fixa no commit de onde veio em skills-lock.json, e uma atualização posterior passa de novo pelo portão antes de substituir qualquer coisa. O passo a passo está em instalar e gerenciar skills.

Skills com escopo de repositório

Um repositório pode trazer suas próprias skills, em qualquer um dos locais convencionais (.agents/skills/, .claude/skills/, .opencode/skills/). Um espaço faz o checkout de cada repositório vinculado lado a lado em repos/<name>/, mas um agente trabalha em um repositório por vez — então ele carrega apenas as skills desse repositório, e elas são trocadas quando ele se move.

Qual repositório está ativo é inferido a partir dos arquivos que o agente toca: escrever um arquivo em repos/<name>/ torna esse o repositório ativo, enquanto apenas ler em outros repositórios não torna, então seguir um símbolo até um serviço vizinho nunca troca o conjunto por baixo de uma tarefa. Em um espaço de repositório único, a resposta já é conhecida antes do primeiro turno.

Esse escopo é uma decisão de orçamento de contexto. O índice de skills fica no prompt a cada turno, enquanto os corpos não ficam, então listar as skills de todos os repositórios de uma vez custa tokens continuamente — e uma skill testing de um serviço engana ativamente quando o trabalho está em outro. O mesmo raciocínio explica por que o índice de um agente carrega só um repositório, mas o compositor não tem esse escopo: nomear uma skill por conta própria é um ato explícito, então /skill:<repo>:<name> alcança qualquer repositório do espaço.

As skills de repositório são carregadas para todos os adaptadores, não apenas para o harness integrado. As skills do repositório ativo são materializadas no diretório de trabalho do agente, que é o caminho que o Claude Code já examina; o mesmo índice é composto no AGENTS.md que o harness integrado lê. As skills de um repositório passam pela mesma varredura fail-closed que uma skill instalada antes de tudo isso acontecer — um repositório com checkout é conteúdo clonado, e seu frontmatter chega a um prompt.

Permissões

Um agente não carrega flags de permissão próprias. Se ele pode criar um commit, fazer push, abrir um pull request, escrever em um rastreador ou alcançar a rede é decidido pelas barreiras de ação — permitir, perguntar primeiro ou negar, no escopo do espaço de trabalho, do agente ou do espaço —, e as mesmas regras valem qualquer que seja o adaptador que o executa.

O que é entregue a uma execução não muda com essas regras. Uma execução em uma worktree do GitHub sempre recebe um token do GitHub somente leitura, e um push é perguntado no momento em que acontece: a configuração do git do agente manda todo push para o GitHub através do Control Center, que aplica a regra Fazer push para um remoto antes de encaminhá-lo.

Consulte Sandbox e segurança para ver como isso funciona, incluindo o que é e o que não é aplicado no nível do sistema de arquivos.

O adaptador decide o que pode ser aplicado

O campo mais determinante de um agente é seu adaptador, porque o transporte do adaptador determina quanto da política do Control Center é de fato aplicável.

Transporte	Adaptadores	O que o Control Center aplica
Harness integrado	Control Center (built-in)	Tudo. A superfície de ferramentas é construída a partir do modo, então uma ferramenta não permitida fica invisível em vez de apenas negada; toda chamada passa pelo portão de aprovação e pelos guardrails de ação; o contrato de conclusão pode dar um empurrão e depois fazer falhar uma execução que termina sem o seu entregável
Claude CLI	Claude Code	As ferramentas `mcp__*` que lhe são fornecidas, mais os comandos `Bash` dele, que um hook envia à política de ações antes de rodarem. As próprias ferramentas de leitura, escrita e edição do Claude vivem no processo dele e rodam sem serem vistas — e ele é iniciado com `--dangerously-skip-permissions`, porque um `claude -p` não interativo bloquearia para sempre no próprio prompt

Concretamente, apenas o harness integrado oferece subagentes, direcionamento durante a execução, pausa e retomada (e, portanto, assumir o controle) e aplicação estrutural de modo. O Claude Code não tem nada disso.

A matriz acima trata do que o Control Center consegue ver e controlar. Por baixo dela, o cc_server envolve a CLI do Claude Code no sandbox do sistema operacional do host onde ele existe — Seatbelt no macOS, bubblewrap no Linux e no WSL2 — então um rm não visto ou uma escrita não vista continua limitado pelo sistema operacional. No Windows não existe backend algum e no Linux ou WSL2 sem bwrap e socat a sondagem não relata nenhum, então ali essas execuções recorrem à sanitização do ambiente, às credenciais intermediadas, aos guardrails sobre as chamadas que o Control Center consegue ver e ao worktree da própria conversa (copy-on-write onde o rift é distribuído; git worktree no Windows).

O que o sandbox não é é um portão. Ele delimita onde um processo pode ler, escrever e se conectar — um modo somente leitura realmente o alcança, na forma de montagens bind somente leitura — mas não consegue interceptar uma chamada, levantar uma aprovação nem dizer depois o que a CLI tentou. Isso, mais as quatro capacidades citadas logo acima, ainda é o que o harness integrado tem e os outros não têm. Consulte Sandbox e segurança.

Um agente sem adaptador recorre a Control Center (built-in) — o loop dentro do servidor, então não há CLI alguma para instalar — e seu log de execução registra cc-harness. Todo agente semeado é criado sem adaptador e sem modelo, então os cinco agentes de um espaço de trabalho novo rodam todos ali, no modelo padrão da Anthropic, até você definir um adaptador e um modelo por agente. A escolha de “adaptador padrão” da configuração inicial é uma preferência do lado do cliente que o servidor nunca lê, e ela não se aplica retroativamente aos agentes já criados.

De onde vêm os agentes

Semeados com o espaço de trabalho. Todo espaço de trabalho — não apenas o primeiro — recebe um CEO mais quatro especialistas (qa, architect, engineer, librarian) que se reportam a ele, criados de forma idempotente em segundo plano quando o espaço de trabalho é criado. Consulte Espaços de trabalho e isolamento.
Adicionados manualmente em Configurações → Espaço de trabalho → Agentes. Pedir a um agente que contrate um colega não cria uma linha; use essa tela.

Estado em tempo real

Um agente não tem uma coluna de status armazenada. Seu estado em tempo real é derivado de seus logs de execução mais recentes a cada vez que ele é lido:

Estado	Significado
`neverRun`	Nenhum log de execução existe
`running`	Pelo menos uma execução está em andamento no momento
`failed`	A execução mais recente deu erro, ou sua vitalidade está failed ou dead
`blocked`	A vitalidade da execução mais recente está blocked, stalled ou looping
`idle`	Todo o resto — o agente já rodou e não tem nada em andamento

Dois outros estados, queued e succeeded, existem para execuções individuais na árvore de execuções da conversa; a lista nunca os produz, porque uma execução concluída estar verde é um fato sobre a execução, e não sobre o agente.

A lista de presença mostra um retrato paralelo e mais grosseiro, sintetizado no lado do servidor a partir de eventos de execução em tempo real — pensando, rodando, bloqueado aguardando aprovação, concluído — que é o que faz os agentes aparecerem ao lado dos humanos. Consulte Multijogador.

Conceitos relacionados

Ciclo de vida do despacho de agentes: o que acontece quando um agente é de fato executado
Modos: a configuração por conversa que molda a superfície de ferramentas de um agente
Multijogador: agentes como atores de pleno direito, presença e o ajuste de autonomia
Sandbox e segurança: o que restringe uma execução hoje
Configuração de agentes: a lista completa de campos