Configuração de agentes

Esta referência lista todos os campos da entidade de agente, além dos enums e das flags que ela usa. Para um passo a passo de criação ou edição de um agente no app, consulte Criar e configurar um agente.

Campos da entidade de agente

Campo	Tipo	Obrigatório	Descrição
`id`	`String`	Sim	Identificador único do agente
`name`	`String`	Sim	Identificador curto para menções com @
`title`	`String`	Sim	Título de função legível por pessoas
`agentMdPath`	`String`	Sim	Caminho absoluto para o arquivo de definição `.md` do agente
`workspaceId`	`String`	Sim	Espaço de trabalho proprietário (não nulo)
`reportsTo`	`String?`	Não	ID do agente pai
`skills`	`AgentSkills`	Sim	Conjunto de identificadores de skills
`persona`	`String?`	Não	Instruções de comportamento em texto livre
`systemPrompt`	`String?`	Não	Substitui o prompt de sistema padrão
`adapterId`	`String?`	Não	ID do adaptador de inferência
`modelId`	`String?`	Não	ID do modelo dentro do adaptador
`strictMode`	`bool`	Não	Padrão `false`. Gravado na linha e no `AGENTS.md` do agente
`effort`	`String?`	Não	ID do nível de raciocínio (por ex. `'low'`, `'xhigh'`), obtido dos `thinkingLevels` do modelo selecionado
`contextSize`	`int?`	Não	Tamanho máximo da janela de contexto
`role`	`AgentRole?`	Não	Função do agente
`monthlyBudgetCents`	`int`	Não	Teto de gastos mensais em centavos (padrão `0`, ilimitado)
`silenceTimeoutMinutes`	`int?`	Não	Substituição do tempo limite de silêncio em minutos; deve ser nulo ou estar entre 1 e 240 (verificado pelo construtor)
`maxConcurrentTasks`	`int`	Não	Padrão `1`. Número de capacidade informado pelo modelo de presença (as contagens de execuções em andamento e na fila são comparadas com ele)
`visibility`	`AgentVisibility`	Não	Padrão `workspace`
`lifecycleStatus`	`AgentLifecycleStatus`	Não	Status de governança (padrão `active`). Gravado pela parada forçada do orçamento e exibido no organograma e na lista de presença. O despacho ainda aceita trabalho de um agente `paused`
`budgetPolicyId`	`String?`	Não	ID da política de orçamento compartilhada; quando nulo, `monthlyBudgetCents` se aplica diretamente
`runtimeProfileId`	`String?`	Não	ID do perfil de execução personalizado
`createdAt`	`DateTime`	Sim	Carimbo de data e hora de criação

name e title precisam ambos ser não vazios (verificado pelo construtor). O monthlyBudgetCents padrão de 0 significa ilimitado. Defina um teto com agents.upsert.

Enum AgentRole

Função	Rótulo	Descrição
`ceo`	CEO	Coordenação e delegação
`coder`	Coder	Implementação de código
`reviewer`	Reviewer	Revisão e análise de PR
`qa`	QA	Testes e garantia de qualidade
`designer`	Designer	Implementação de UI/UX
`security`	Security	Revisão e auditoria de segurança
`devops`	DevOps	Infraestrutura e implantação
`pm`	PM	Gestão de produto
`general`	General	Flexível e multiuso

Enum AgentVisibility

Valor	Descrição
`workspace`	O padrão; valores armazenados desconhecidos ou nulos são interpretados como ele
`private`	Privado para o usuário que o criou

Enum AgentLifecycleStatus

Valor	Descrição
`active`	O padrão. `isDispatchable` só é verdadeiro para este valor
`paused`	Definido pela parada forçada do orçamento. Exibido na lista de presença; o despacho ainda aceita trabalho
`archived`	Aposentado e oculto das listas de presença ativas

Permissões

Um agente não carrega flags de permissão. Fazer push, abrir e publicar pull requests, escrever em um rastreador e a saída de rede são classes de ação (gitPush, prCreate, prPublish, vendorSyncWrite, networkEgress) que as barreiras resolvem no escopo do espaço de trabalho, do agente ou do espaço. O token do GitHub de uma execução tem sempre escopo de leitura; os pushes passam pelo gateway de execuções de agentes, que pergunta à regra gitPush antes de encaminhá-los.

AgentSkills

Um conjunto imutável e insensível a maiúsculas e minúsculas de identificadores de skills. No despacho, esses slugs são sincronizados como links de skills no overlay do agente; o harness então carrega automaticamente o frontmatter das skills vinculadas no prompt.

{'flutter', 'dart', 'rest-api'}

AgentLiveState (derivado)

Não armazenado. Sete valores. A ordem de declaração é a ordem de prioridade (sortPriority, fixada por um teste), que é a ordem pela qual a lista ordena os agentes:

Estado	`sortPriority`	Condição
`running`	0	Qualquer log de execução tem status `running`
`blocked`	1	A vitalidade da execução mais recente é `blocked`, `stalled` ou `looping`
`failed`	2	O status da execução mais recente é `error`, ou sua vitalidade é `failed` ou `dead`
`queued`	3	Uma execução foi despachada mas não está em execução — parada atrás de outra execução do mesmo agente, ou gravada mas ainda não iniciada
`succeeded`	4	A execução terminou com sucesso
`idle`	5	O agente já rodou antes e não tem nada em andamento
`neverRun`	6	Não existe nenhum log de execução

queued e succeeded são apenas por execução. deriveAgentLiveState, que calcula o estado de um agente na lista, nunca produz nenhum dos dois — ele retorna neverRun, running, failed, blocked ou idle.