Manifest

Usa questa pagina per identificare i tipi di manifest, i metadati comuni, la validazione e l'editor.

Ogni file di configurazione contiene uno o più manifest, separati da ---. La cartella in cui sta il file non conta: è il kind a dire che cos'è un manifest. I file e le cartelle il cui nome inizia con . o _ vengono saltati: così una ConfigMap di Kubernetes montata come cartella carica ogni file una volta sola, e un input tenuto accanto ai manifest (_inputs/, _request.yaml) non viene mai letto come manifest.

apiVersion: afe.dev/v1alpha1
kind: Agent
metadata:
  name: reviewer                      # obbligatorio, unico per kind
  labels:                             # facoltativo, stringa → stringa
    team: editorial
  annotations:                        # facoltativo; la descrizione è una di queste
    afe.dev/description: Checks the text
spec:
  model: cheap
  systemPromptFile: prompts/reviewer.md   # relativo a questo file
  reads:
    - text-request
    - text
  writes: review

Ogni manifest è un oggetto Kubernetes valido, così gli stessi file si potranno applicare a un cluster:

• metadata.name e gli id dei nodi sono label DNS-1123: lettere minuscole, cifre e -, che iniziano e finiscono con una lettera o una cifra, al massimo 63 caratteri (text-request, non text_request);
• metadata contiene solo name, labels e annotations, con chiavi e valori Kubernetes;
• la descrizione è l'annotation afe.dev/description.

Un prompt è testo inline (systemPrompt: |) oppure un file accanto al manifest (systemPromptFile), mai entrambi. Su Kubernetes, dove una custom resource non ha file accanto, usa la forma inline.

Le chiavi dentro spec sono in camelCase. Una chiave sconosciuta è un errore, tranne i parametri dei tipi di nodo forniti dai plugin.

Kind

Kind	Cosa dichiara
Flow	Un grafo di nodi e archi, l'artefatto di ingresso, il workspace e il budget.
Lane	Un sotto-flusso riusabile e parametrizzato, usato da un nodo lane o map.
Agent	Un agente: harness, modello, prompt, artefatti che legge e scrive, tool, budget.
Schema	I campi di un artefatto: string, int, number, bool, enum[a|b], list[…], object.
Project	Dove lavorano gli agenti: una cartella o un repository git, sandbox e CI. La forge è none o github.
Script	Un comando personalizzato per un nodo deterministico; gira nella sandbox del progetto.
Model	Un alias di modello (metadata.name, per esempio cheap): provider, modello, prezzo, fallback.
McpServer	Un server MCP, i cui tool gli agenti usano come mcp:<server>.<tool>.
AcpAgent	Un agente esterno raggiunto via ACP.
Plugin	Un plugin fuori processo raggiunto dal motore via JSON-RPC 2.0 (stdio o HTTP).
Runtime	Il manifest del motore stesso: store, broker, tracer, cartella di lavoro e sandbox.

I segreti non si scrivono mai nei manifest: un manifest indica la variabile d'ambiente che li contiene (apiKeyEnv, tokenEnv).

Una lettura opzionale finisce con ? (- review?): l'agente la riceve solo se esiste.

Le durate si scrivono come 30s, 15m, 4h oppure in secondi.

Supporto nell'editor

Il JSON Schema di tutti i kind è generato dai modelli del motore. Sta nel repository in schemas/afe.dev-v1alpha1.json e su questo sito in /schemas/afe.dev-v1alpha1.json.

Con lo YAML language server (VS Code, PyCharm, Neovim…) basta questa riga in cima al file:

# yaml-language-server: $schema=../schemas/afe.dev-v1alpha1.json

Validazione

Il caricamento di una configurazione segnala tutti i problemi insieme, ciascuno con file, documento e percorso:

flows.yaml#2: spec.edges[2]: a feedback edge needs `maxRounds`, or the flow could loop forever
agents.yaml#1: spec.model: unknown Model 'smart' (known: cheap)

Oltre alla struttura, la validazione controlla:

• i riferimenti tra manifest (agenti, lane, schemi, modelli, script, server MCP, agenti ACP);
• il grafo: un solo punto di partenza, ogni nodo raggiungibile, END raggiungibile, nessun ciclo senza maxRounds, un modo per scegliere tra più uscite;
• gli artefatti: ogni lettura ha chi la scrive a monte, le letture dopo un choose sono opzionali (nome?), le condizioni citano artefatti esistenti, rami paralleli non scrivono mai lo stesso artefatto;
• workspace e sandbox: esiste un progetto adatto, gli agenti che eseguono comandi hanno una sandbox, i passi git girano su un workspace git.

I tipi di nodo e gli harness forniti dai plugin producono un avviso finché i plugin non vengono caricati.

Vedi anche

• Flow per grafi e campi di esecuzione.
• Agent per modello, prompt e tool.
• Runtime per store, broker, tracing e sandbox.