Vai al contenuto

OpenCode Agent

OpenCode e l'agente operativo di ALIDA. Espone le sue API e streaming SSE e puo essere specializzato per un dominio attraverso un dataset di discovery.

Specializzazione tramite dataset

Durante l'avvio, OpenCode scopre il contenuto del dataset disponibile. Una struttura tipica e:

skills/
tools/
plugins/
agents/

Prompt, skill, tool, agenti ausiliari e documentazione presenti nel dataset determinano la specializzazione effettiva dell'agente. Lo stesso runtime puo quindi essere riutilizzato in domini diversi cambiando il dataset.

Service Writer di ALIDA

Nel caso del Service Writer, OpenCode lavora su una repository associata alla BDA e usa un dataset orientato ad ALIDA. Il flusso comprende in genere:

  1. definizione o aggiornamento di .alida/spec.md;
  2. lettura della documentazione rilevante;
  3. implementazione del codice del Service;
  4. generazione e validazione di src/arguments.py e meta-model.json;
  5. produzione della documentazione e della configurazione CI;
  6. test, commit, push e apertura della merge request dopo il successo della pipeline.

All'avvio, OpenCode crea o clona una repository nel namespace della BDA e crea o recupera il corrispondente esperimento MLflow. Il BDAID mantiene il legame tra la chat, gli artefatti e il contesto operativo.

OpenCode puo usare capability fornite da un server MCP, incluso un ADK Agent. Non puo invece essere usato come server MCP da ADK.

Workflow OpenCode con servizi MCP

Per configurarlo nella chat, vedere Configurare un agente nella chat. Per capire il tracciamento delle attivita, vedere Osservabilita con MLflow.

| GARAGE_DEFAULT_BUCKET | Local Compose | Bucket used by the local Garage dataset loader. | | GARAGE_DEFAULT_ACCESS_KEY, GARAGE_DEFAULT_SECRET_KEY | Local Compose | Credentials for the local Garage bucket. | | GARAGE_LOAD_PREFIX | No | Garage prefix containing the agent dataset. Defaults to agents. | | GARAGE_URL | No | Local S3 endpoint supplied to the runtime. Defaults to http://s3:3900. | | GARAGE_REGION | No | Garage S3 region. Defaults to garage. |

REPO_DIR and OPENCODE_PORT are advanced runtime overrides. They default to /workspace/service and 10000; changing OPENCODE_PORT also requires updating the Compose port mapping. In Alida, the platform supplies the execution identity, GitLab, S3, and MLflow settings; the local Garage variables are not needed.

Specializzazione del dataset

Il dataset determina cosa conosce l'agente di coding e come si comporta. Per l'agente Alida-service, il dataset ALIDA fornisce prompt, skill e il file alida-documentation.md specifici per ALIDA.

Per generalizzare il runtime, fornire un dataset per il dominio di destinazione. I file mantengono i relativi percorsi quando vengono uniti in /opencode. Una struttura tipica del dataset e:

AGENTS.md
agents/
  domain-expert.md
skills/
  domain-workflow/
    SKILL.md
tools/
  domain-tool.ts
plugins/
  domain-plugin.ts
reference-documentation.md

I contenuti del dataset hanno ruoli distinti:

  • AGENTS.md contiene le istruzioni condivise e globali che guidano l'agente principale e i sottoagenti.
  • agents/ contiene file Markdown, uno per sottoagente specializzato. Ogni file ne definisce il ruolo, le competenze e le istruzioni operative, ad esempio per un esperto del dominio. Per ulteriori esempi su come definire un sottoagente, fare riferimento a Agenti | OpenCode.
  • skills/ contiene procedure riutilizzabili. Ogni skill ha una propria cartella e un file SKILL.md che descrive quando applicarla e quali passaggi eseguire. Per maggiori dettagli, vedere Competenze dell'agente | OpenCode.
  • tools/ contiene strumenti personalizzati che l'agente puo invocare durante una conversazione. Gli strumenti sono definiti in file JavaScript o TypeScript e possono eseguire integrazioni o script del dominio. Per maggiori dettagli, vedere Strumenti personalizzati | OpenCode.
  • plugins/ contiene plugin JavaScript o TypeScript che estendono OpenCode tramite hook sugli eventi, ad esempio per integrare servizi esterni, modificare il comportamento dell'agente o aggiungere strumenti. Per maggiori dettagli, vedere Plugin | OpenCode.
  • I file di documentazione di riferimento del dominio restano fuori da agents/ e vengono richiamati dalle istruzioni o dai prompt quando necessario.

L'agente può essere configurato con più porte di ingresso, tutte di tipo dataset. Ogni porta può collegare un dataset ALIDA oppure un server MCP remoto.

Strumenti dell'agente e ciclo operativo

L'agente principale e istruito per sviluppare servizi ALIDA dispone dei seguenti tool:

  • validate-metamodel: convalida meta-model.json e il relativo file src/arguments.py rispetto al contratto dei servizi ALIDA.
  • embed-documentation: copia documentation.md in meta-model.json:markDown.value, da cui la piattaforma ricava il manuale visualizzato nell'interfaccia utente.
  • generate-gitlab-ci: genera la configurazione CI standard di ALIDA, inclusa la fase di registrazione del servizio.
  • commit-and-push-service: esegue il commit della repository del servizio e pubblica il branch di lavoro dopo aver verificato che corrisponda alla repository configurata in GIT_URL.
  • get_useful_info: restituisce informazioni deterministiche sull'ambiente di esecuzione, tra cui la data corrente e l'utente che sta operando.
  • gitlab-mcp: server MCP che consente all'agente di interagire con repository, issue, merge request e pipeline GitLab.

Il ciclo operativo inizia con la creazione o la revisione di .alida/spec.md, quindi legge la documentazione ALIDA relativa alle integrazioni richieste. L'agente implementa il servizio, delega al sottoagente metamodel-writer la generazione di src/arguments.py e meta-model.json, convalida il risultato e delega al sottoagente documentation-writer la documentazione destinata agli utenti. Inserisce quindi la documentazione nel meta-modello, genera la configurazione CI e scrive i test end-to-end. Infine registra l'iterazione, pubblica il branch feat/<service-name>, attende la pipeline e, se necessario, corregge gli errori della pipeline. Dopo una validazione completata con successo, apre una merge request. Il merge in develop o dev avvia la build e la registrazione del servizio usando il meta-model.json fornito.

 flowchart TD
   A["Richiesta dell'utente"] --> B{"spec.md
esiste?"}

   B -- No --> C["Iterazione 0 · nuovo servizio
· v1.0.0"]
   B -- Si --> D["Revisione · incrementa un
segmento di versione"]

   C --> E["Scrivi .alida/spec.md
proponi valori predefiniti,
confrontati con l'utente"]
    D --> E

   E --> F["Leggi la documentazione
ALIDA"]
   F --> G["Scrivi il codice del servizio
main.py, Dockerfile,
docker-compose,
requirements.txt"]
   G --> H["Sottoagente metamodel-writer
arguments.py + meta-model.json"]
   H --> I{"validate-
metamodel
OK?"}

   I -- KO --> H
   I -- OK --> J["Sottoagente documentation-writer
documentation.md"]

   J --> K["Strumento embed-documentation
documentazione nel meta-modello"]
   K --> L["Skill write-service-tests
gitlab-ci.yml + directory tests"]
   L --> M["Sottoagente history-summarizer
aggiunge una voce a iterations.md"]
   M --> N["Strumento commit-and-push-service
sul branch feat/<service-name>"]
   N --> O["Attendi la pipeline"]
   O --> P{"Esito della
pipeline?"}

   P -- OK --> Q["Crea una merge request
verso develop"]
   Q --> R["Comunica l'URL della MR
FINE"]

   P -- KO --> S{"Tentativi di
correzione
rimanenti?"}
   S -- No --> T["Comunica l'ultimo log
FINE"]
   S -- "Si, massimo 2" --> U["Analizza il log e correggi"]
    U --> N