O modelo de agentes

O que é um agente?

Um agente é um ator com um nome, uma persona, um conjunto de skills e um adaptador em que corre. Os agentes são identidades de pleno direito, tal como os humanos: criam mensagens, são donos de tickets, deixam revisões e aparecem na mesma lista. São eles que fazem o trabalho.

Cada agente pertence a exatamente um espaço de trabalho. Esta é uma invariante rígida — agent.workspaceId nunca é nulo, é o próprio espaço de trabalho do agente que escolhe o ficheiro de base de dados onde ficam as suas linhas, e criar um agente sem espaço de trabalho é recusado.

Um agente é também um diretório. A sua definição vive em agents/<slug>/AGENTS.md, no diretório de dados do espaço de trabalho, e as skills que detém estão ligadas por ligação simbólica em agents/<slug>/.agents/skills. A linha na base de dados e o ficheiro são escritos em conjunto. A criação é idempotente: mesmo que a linha do agente já exista, os ficheiros em disco e as ligações das skills são na mesma reescritos. Quem faz esta chamada em produção é a criação do espaço de trabalho, não cada arranque do servidor.

O que um agente traz

Atributo	O que faz
`name`	Identificador curto do tipo slug (`architect`, `qa`). É também aquilo em que as `@mentions` são resolvidas
`title`	Cargo legível por humanos
`persona`	Instruções livres de personalidade e comportamento, injetadas como secção do prompt
`systemPrompt`	Instruções adicionais opcionais, injetadas como secção “Agent instructions” — não substituem o resto do prompt montado
`skills`	Conjunto de nomes de skills insensível a maiúsculas e minúsculas, espelhado como ligações de skills no disco
`adapterId`	O runner para o qual o agente é despachado. Nulo recorre ao ciclo integrado
`modelId`	O modelo dentro desse adaptador
`effort`	Nível de raciocínio, retirado do vocabulário do próprio modelo selecionado
`contextSize`	Substituição da janela de contexto
`silenceTimeoutMinutes`	Substituição por agente (1–240) do vigilante de silêncio
`reportsTo`	Id do agente superior — a cadeia hierárquica que o organigrama desenha

Edita tudo isto em Definições → Espaço de trabalho → Agentes. Novo agente cria um agente sem nome que depois preenches.

Skills

As skills são nomes insensíveis a maiúsculas e minúsculas na entidade do agente. Acontecem duas coisas distintas com elas:

Os nomes são listados no prompt montado sob um título “Skills”. É tudo o que o conjunto da entidade faz por si só — não existe nenhuma biblioteca de prompts por skill indexada por ele.
O diretório de cada skill com nome (skills/<slug>/SKILL.md no espaço de trabalho) é ligado à própria pasta do agente. No harness integrado, o frontmatter das skills ligadas é carregado automaticamente no prompt de sistema e o agente lê um corpo a pedido; escrever /skill:<name> numa conversa carrega esse corpo como diretiva para o turno.

As skills obtidas do exterior passam por uma análise fail-closed da cadeia de abastecimento entre a obtenção e a escrita — nenhum conteúdo de skill chega ao disco ou a um prompt sem um veredicto. O exterior são repositórios do GitHub que registas tu próprio como fontes de skills: não existe nenhuma loja curada, por isso os metadados do próprio repositório (a descrição, as estrelas, o nome da skill) são dados de apresentação não fidedignos e o veredicto da análise é o único sinal de segurança. Uma instalação obtém o diretório completo da skill, fixa-a ao commit de onde veio em skills-lock.json, e uma atualização posterior volta a passar o gate antes de substituir seja o que for. O procedimento está em instalar e gerir skills.

Skills com âmbito de repositório

Um repositório pode trazer as suas próprias skills, em qualquer dos locais convencionais (.agents/skills/, .claude/skills/, .opencode/skills/). Um espaço faz o checkout de todos os repositórios ligados, lado a lado, em repos/<name>/, mas um agente trabalha num repositório de cada vez — por isso leva consigo apenas as skills desse repositório, e elas são trocadas quando ele muda de repositório.

Qual é o repositório ativo é inferido a partir dos ficheiros que o agente toca: escrever um ficheiro em repos/<name>/ torna esse o repositório ativo, ao passo que apenas ler entre repositórios não o faz, pelo que seguir um símbolo até um serviço vizinho nunca troca o conjunto debaixo de uma tarefa. Num espaço com um único repositório, a resposta é conhecida antes do primeiro turno.

Este âmbito é uma decisão de orçamento de contexto. O índice de skills está no prompt em todos os turnos, ao contrário dos corpos, por isso listar de uma vez as skills de todos os repositórios custa tokens continuamente — e uma skill testing de um serviço induz ativamente em erro quando o trabalho está noutro. A mesma lógica explica por que o índice de um agente leva apenas um repositório, ao passo que o compositor não tem esse âmbito: nomeares tu uma skill é um ato explícito, pelo que /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á analisa; o mesmo índice é composto no AGENTS.md que o harness integrado lê. As skills de um repositório passam a mesma análise fail-closed que uma skill instalada antes de tudo isto acontecer — um repositório extraído é conteúdo clonado, e o seu frontmatter chega a um prompt.

Permissões

Um agente não transporta indicadores de permissão próprios. Se pode criar um commit, fazer push, abrir um pull request, escrever num rastreador ou chegar à rede é decidido pelas barreiras de ação — permitir, perguntar primeiro ou negar, no âmbito do espaço de trabalho, do agente ou do espaço —, e as mesmas regras aplicam-se seja qual for o adaptador que o executa.

Aquilo que é entregue a uma execução não muda com essas regras. Uma execução numa worktree do GitHub recebe sempre um token do GitHub só de leitura, e um push é perguntado no momento em que acontece: a configuração do git do agente encaminha cada push para o GitHub através do Control Center, que aplica a regra Fazer push para um remoto antes de o reencaminhar.

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

O adaptador decide o que pode ser aplicado

O campo com mais consequências de um agente é o seu adaptador, porque o transporte do adaptador determina quanto da política do Control Center é realmente 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, pelo que uma ferramenta não permitida é invisível em vez de meramente recusada; cada chamada passa o gate de aprovação e os guardrails das ações; o contrato de conclusão pode insistir e depois fazer falhar uma execução que termine sem o seu entregável
Claude CLI	Claude Code	As ferramentas `mcp__*` que lhe são servidas, mais os seus comandos `Bash`, que um hook envia para a política de ações antes de correrem. As ferramentas de leitura, escrita e edição do próprio Claude vivem no seu processo e correm sem serem vistas — e é iniciado com `--dangerously-skip-permissions`, porque um `claude -p` não interativo bloquearia indefinidamente no seu próprio pedido

Concretamente, apenas o harness integrado suporta subagentes, orientação a meio da execução, pausa e retoma (e, portanto, a assunção de controlo) e a aplicação estrutural do modo. O Claude Code não tem nada disto.

A matriz acima diz respeito ao que o Control Center consegue ver e condicionar. Por baixo dela, o cc_server envolve a CLI do Claude Code na sandbox do sistema operativo do anfitrião, onde ela exista — Seatbelt no macOS, bubblewrap no Linux e no WSL2 —, pelo que um rm invisível ou uma escrita invisível continuam limitados pelo sistema operativo. No Windows não existe backend nenhum e, no Linux ou no WSL2 sem bwrap e socat, a sonda não reporta nenhuma, pelo que aí essas execuções recorrem à sanitização do ambiente, às credenciais mediadas, aos guardrails das chamadas que o Control Center consegue ver e à worktree da própria conversa (copy-on-write onde o rift é distribuído; git worktree no Windows).

O que a sandbox não é é um gate. Limita onde um processo pode ler, escrever e ligar-se — um modo só de leitura chega mesmo a alcançá-la, sob a forma de montagens bind de leitura apenas — mas não consegue intercetar uma chamada, levantar um pedido de aprovação nem dizer-te depois o que a CLI tentou. Isso, mais as quatro capacidades indicadas acima, continua a ser o que o harness integrado tem e os outros não têm. Consulta Sandbox e segurança.

Um agente sem adaptador recorre a Control Center (built-in) — o ciclo dentro do servidor, pelo que não há nenhuma CLI para instalar — e o seu registo de execução regista cc-harness. Todos os agentes criados com o espaço de trabalho ficam sem adaptador e sem modelo, pelo que os cinco agentes de um espaço de trabalho novo correm todos aí, no modelo predefinido da Anthropic, até definires um adaptador e um modelo por agente. A escolha de “adaptador predefinido” na configuração inicial é uma preferência do lado do cliente que o servidor nunca lê, e não é aplicada retroativamente aos agentes já criados.

De onde vêm os agentes

Criados com o espaço de trabalho. Todos os espaços de trabalho — não apenas o primeiro — recebem um CEO e quatro especialistas (qa, architect, engineer, librarian) que lhe reportam, criados de forma idempotente em segundo plano quando o espaço de trabalho é criado. Consulta Espaços de trabalho e isolamento.
Adicionados à mão em Definições → Espaço de trabalho → Agentes. Pedir a um agente que contrate um colega não cria uma linha; usa esse ecrã.

Estado em direto

Um agente não tem nenhuma coluna de estado guardada. O seu estado em direto é derivado dos seus registos de execução mais recentes sempre que é lido:

Estado	Significado
`neverRun`	Não existe nenhum registo de execução
`running`	Há pelo menos uma execução em curso
`failed`	A execução mais recente deu erro, ou a sua vivacidade está em falha ou morta
`blocked`	A vivacidade da execução mais recente está bloqueada, paralisada ou em ciclo
`idle`	Todo o resto — o agente já correu antes e não tem nada em curso

Existem mais dois estados, queued e succeeded, para execuções individuais na árvore de execuções da conversa; a lista nunca os produz, porque o facto de uma execução terminada estar verde é um facto sobre a execução, não sobre o agente.

A lista de presenças mostra um retrato paralelo e mais grosseiro, sintetizado do lado do servidor a partir de eventos de execução em direto — a pensar, em execução, bloqueado à espera de aprovação, concluído —, que é o que faz os agentes aparecerem ao lado dos humanos. Consulta Multijogador e presença.

Conceitos relacionados

Ciclo de vida do despacho de agentes: o que acontece quando um agente é realmente executado
Modos: a definição por conversa que molda a superfície de ferramentas de um agente
Multijogador e presença: os agentes como identidades de pleno direito, a presença e o controlo de autonomia
Sandbox e segurança: o que limita uma execução hoje
Configuração de agentes: a lista completa de campos