Tutti gli articoli

Agenti AI: Guida a OpenCode, Pi Coding Agent e Kilo Code CLI

coding agent minimal

Questa guida fornisce un’introduzione pratica e approfondita all’utilizzo di tre potenti strumenti per lo sviluppo assistito dall’IA: OpenCode, Pi Coding Agent e Kilo Code CLI. Ci concentreremo sull’installazione, la configurazione di base, i comandi essenziali, la gestione di skill e sub-agenti, e l’integrazione con servizi esterni per aiutarti a integrare questi agenti nel tuo flusso di lavoro in modo efficace.

1. OpenCode

OpenCode è un agente di programmazione AI open source disponibile come interfaccia per terminale (TUI), app desktop o estensione per IDE.

1.1 Installazione

Il modo più semplice per installare OpenCode è tramite lo script di installazione:

curl -fsSL https://opencode.ai/install | bash

In alternativa, previa installazione di nodejs, puoi installarlo con npm:

npm install -g opencode-ai

Su sistemi Windows la documentazione ufficiale consiglia si usare WSL. Se non sai cosa è WSL ti consiglio questa guida. In breve dopo aver installato WSL puoi installare OpenCode con

curl -fsSL https://opencode.ai/install | bash

Da dentro un terminale Linux con WSL naviga nella cartella di interesse ed esegui il comando opencode

cd /mnt/c/Users/YourName/project
opencode

Usando WSL i file di configurazione e sessioni sono memorizzati dentro ~/.local/share/opencode/

1.2 Configurazione Iniziale

Dopo l’installazione, devi configurare un provider LLM. OpenCode supporta vari provider, e puoi connetterti tramite il comando /connect nella TUI:

  1. Esegui /connect nella TUI di OpenCode.
  2. Seleziona il tuo provider (esempio OpenAI, ANtropic, OpenRouter, eccetera)
  3. Incolla la chiave API quando richiesto.

N.B. Nel caso di utilizzo di Requesty se vedi un sottoinsieme di modelli (e non tutti i modelli disponibili sul sito) li puoi settare andando a modificare il file di configurazione opencode.json da creare nella cartella ~/.config/opencode/. Inserisci l’API di Requesty e aggiungi nella sezione models i modelli desiderati:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "requesty-extra": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Requesty (Extra Models)",
      "options": {
        "baseURL": "https://router.requesty.ai/v1",
        "apiKey": "....."
      },
      "models": {
        "zai/GLM-5.1":         { "name": "GLM 5.1 (Zai)" },
        "inceptron/glm-5.1":   { "name": "GLM 5.1 (Inceptron)" },
        "novita/zai-org/glm-4.6": { "name": "GLM 4.6 (Novita)" }
      }
    }
  }
}

Per rendere effettive le modifiche riavvia OpenCode. I nuovi modelli compariranno sotto il gruppo Requesty (Extra Models)

1.3 Inizializzazione del Progetto

Per utilizzare OpenCode su un progetto esistente:

  1. Naviga nella directory del tuo progetto cd /path/to/project
  2. Avvia OpenCode opencode
  3. Inizializza OpenCode per il progetto con il comando /init. Questo farà analizzare il progetto a OpenCode e creerà un file AGENTS.md nella root del progetto. Questo aiuta OpenCode a comprendere la struttura e gli stili di codice utilizzati.

Il file AGENTS.md nella root del progetto verrà incluso nel contesto della conversazione. Se hai già un file AGENTS.md, eseguendo il comando init, questo migliorerà il contenuto del file, mantenendo le istruzioni precedentemente contenute.

Il file AGENTS.md può essere definito in diverse posizioni

  1. file AGENTS.md nella root del progetto
  2. file AGENTS.md globale nella cartella ~/.config/opencode/ che verrà preso in considerazione da ogni sessione opencode

Opencode può anche leggere i file markdown creati per Claude Code

  1. CLAUDE.md nella root del progetto, per regole relative a un progetto
  2. ~/.claude/CLAUDE.md per regole globali
  3. ~/.claude/skills/ per le skills degli agents

L’ordine di precedenza di questi files markdown è il seguente, dove il primo trovato vince su quelli successivi

  1. File locali AGENTS.md, CLAUDE.md
  2. File globale ~/.config/opencode/AGENTS.md
  3. Claude Code file ~/.claude/CLAUDE.md

1.4 Comandi Interni Essenziali

OpenCode include diversi comandi integrati per gestire il flusso di lavoro:

  • /init Inizializza OpenCode per il progetto corrente, creando AGENTS.md nella directory corrente.
  • /connect Configura i provider LLM e le chiavi API.
  • <TAB> Passa dalla modalità Plan Mode alla modalità Build Mode, e viceversa
  • /models Mostra i modelli LLM disponibili
  • /undo Annulla l’ultima serie di modifiche apportate dall’agente.
  • /redo Ripristina le modifiche annullate.
  • /compact Compatta facendo un riassunto della sessione corrente
  • /new avvia una nuova sessione
  • /sessions mostra le sessioni esistenti, utile anche per cambiare sessione
  • /help Mostra la guida e i comandi disponibili.

1.5 Pianifica e Scrivi

Opencode raccomanda prima di richiedere una modifica di pianificare tale modifica. Per fare ciò premi <TAB> per passare nella modalità Plan di modo da non scrivere modifiche nel codice. Una volta deciso e modificato il piano di azione proposto è possibile scrivere e implementare tali modifiche nel codice. Per fare ciò premere di nuovo <TAB> per passare alla modalità BUILD e chiedere al modello llm di implemtare tali modifiche.

Per modifiche più modeste è possibile chiedere direttamente al modello LLM di implemtare le modifiche, senza passare dallo step di pianificazione.

1.6 Comandi Personalizzati

Puoi estendere le funzionalità di OpenCode creando comandi personalizzati per automatizzare task ripetitivi. Questi comandi si definiscono tramite file Markdown nella directory commands/ (globale in ~/.config/opencode/commands/ o locale in .opencode/commands/).

Esempio di creazione di un comando .opencode/commands/test.md richiamabile con /test:

---
description: Esegue i test con copertura
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---
Esegui la suite di test completa con il report di copertura e mostra eventuali fallimenti.
Concentrati sui test falliti e suggerisci correzioni.

Puoi eseguire questo comando digitando /test nella TUI.

Nei prompt dei comandi personalizzati puoi usare:

  • $ARGUMENTS o $1, $2 per passare argomenti.
  • !comando per inserire l’output di un comando bash (es. !npm test).
  • @file per includere il contenuto di un file specifico.

Per esempi dettagliati vedere la documentazione

1.7 Agenti e Sub-agenti

In Opencode esistono due tipi di agenti: agenti primari e sub-agenti. Questi vengono utilizzati per gestire compiti diversi.

Con gli agenti primari ci interagisco direttamente. Posso switchare da un agente primario all-altro con il tasto TAB. Gli agenti primari pre esistenti sono BUILD e PLAN:

Agenti Primari Integrati:

  • Build: L’agente predefinito con tutti gli strumenti abilitati (scrittura, modifica, bash). Ideale per lo sviluppo attivo.
  • Plan: Un agente limitato per la pianificazione e l’analisi. Di default, richiede conferma (ask) per modifiche ai file e comandi bash. Utile per analizzare il codice senza apportare modifiche dirette.

I sub-agenti vengono invocati dagli agenti primari per compiti specifici. Li posso invocare menzionandoli con il carattere @ (es. @general aiutami a cercare questa funzione).

Opencode dispone di 3 sub-agenti installati:

  • General: Agente general-purpose per ricerche complesse e task multi-step. Ha accesso completo agli strumenti (tranne todo).
  • Explore: Agente in sola lettura per esplorare rapidamente la codebase. Non può modificare file.
  • Scout: Agente in sola lettura per esplorare documentazione e dependency

Puoi creare agenti personalizzati configurandoli nel file opencode.json o creando file Markdown nella directory agents/ (es. .opencode/agents/review.md).

1.8 Integrazione con Servizi Esterni (MCP)

OpenCode supporta il Model Context Protocol (MCP) per integrare strumenti e servizi esterni. I server MCP possono essere locali o remoti e si configurano nel file opencode.json (o opencode.jsonc).

Aggiungere un Server MCP Locale:

{
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_env_var_value",
      }
    }
  }
}

Aggiungere un Server MCP Remoto (con OAuth):

OpenCode gestisce automaticamente l’autenticazione OAuth per i server remoti.

{
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}

Se il server richiede autenticazione, OpenCode ti chiederà di autenticarti al primo utilizzo. Puoi anche gestire l’autenticazione manualmente con i comandi CLI:

  • opencode mcp auth <server-name>: Avvia l’autenticazione.
  • opencode mcp list: Elenca i server MCP e il loro stato.
  • opencode mcp logout <server-name>: Rimuove le credenziali.

Una volta configurato, puoi chiedere a OpenCode di utilizzare lo strumento MCP nei tuoi prompt (es. usa lo strumento mcp_everything per...).

1.9 Altro da sapere

Per fare riferimento a un file nel progetto usare il simbolo @

How is auth handled in @packages/functions/src/api/index.ts?

Per eseguire un comando shell, far precedere comando con il simbolo !

!ls -la

2. Pi Coding Agent

Pi Coding Agent è un agente di codifica open source minimale, focalizzato sull’essere estensibile e self-documenting. A differenza di altri agenti, Pi inizia con un set limitato di strumenti (read, write, edit, bash) e permette agli utenti di costruire il proprio ambiente.

2.1 Installazione

Pi Coding Agent può essere installato globalmente tramite npm o pnpm:

npm install -g @earendil-works/pi-coding-agent
# oppure
pnpm add -g @earendil-works/pi-coding-agent

2.2 Utilizzo Base e Comandi

Dopo l’installazione, avvia Pi nel tuo terminale digitando pi. La sua filosofia è quella di essere un assistente di codifica minimale e personalizzabile.

  • Invio messaggi: Premi Enter per inviare un messaggio di “steering” (interrompe gli strumenti correnti). Premi Alt+Enter per un messaggio di “follow-up” (attende che l’agente finisca).
  • Cambio modello: Usa /model o Ctrl+L per cambiare modello durante la sessione. Ctrl+P per scorrere i preferiti.
  • Navigazione sessione: Le sessioni sono salvate come alberi. Usa /tree per navigare a un punto precedente.
  • Esportazione: Usa /export per esportare in HTML o /share per creare un gist GitHub condivisibile.

2.3 Estensioni, Skill e Sub-agenti

Pi non ha funzionalità come sub-agenti o plan mode integrate di default, ma ti permette di costruirle o installarle tramite pacchetti.

  • Pacchetti (Packages): Puoi installare estensioni, skill, prompt e temi tramite npm o git. 
    pi install npm:@foo/pi-tools
pi install git:github.com/badlogic/pi-doom
  • Sub-agenti: Esistono pacchetti della community (come pi-subagents o @tintinweb/pi-subagents) che aggiungono il supporto per i sub-agenti a Pi. Questi pacchetti definiscono agenti con set di strumenti specifici (es. Explore con solo read, bash, grep, find, ls) [6].
  • Integrazione MCP: Pi supporta l’integrazione con server MCP tramite estensioni specifiche (es. pi-mcp), permettendo di collegarsi a servizi esterni come Chrome DevTools o altri strumenti compatibili con MCP.

3. Kilo Code CLI

Kilo Code CLI è una potente interfaccia a riga di comando che fa parte della piattaforma di ingegneria agentica Kilo. È un fork di OpenCode, migliorato per integrarsi nell’ecosistema Kilo, offrendo funzionalità avanzate di generazione di codice, automazione e debugging.

3.1 Installazione

Puoi installare Kilo Code CLI globalmente usando npm:

npm install -g @kilocode/cli

In alternativa, puoi eseguirlo direttamente con npx senza installazione globale:

npx @kilocode/cli

3.2 Utilizzo Base e Modalità (Agenti)

Dopo l’installazione, puoi avviare Kilo in qualsiasi directory di progetto:

kilo

Kilo offre diverse modalità (o agenti) per gestire compiti specifici:

  • Architect (Pianificazione): Utilizzato per la pianificazione e l’analisi. Simile alla modalità Plan di OpenCode.
  • Coder (Codifica): L’agente principale per la generazione e la modifica del codice.
  • Debugger (Debugging): Specializzato nell’individuazione e risoluzione di bug.

Puoi anche creare modalità personalizzate per adattare Kilo al tuo flusso di lavoro.

3.3 Comandi CLI Utili

Kilo Code CLI offre diversi comandi per gestire l’ambiente e le integrazioni:

  • kilo run --auto "messaggio": Esegue Kilo in modalità autonoma (ideale per CI/CD). Disabilita le richieste di permesso.
  • kilo mcp: Gestisce i server MCP.
    • kilo mcp add: Aggiunge un server MCP.
    • kilo mcp list (o ls): Elenca i server MCP e il loro stato.
    • kilo mcp auth [name]: Autentica con un server MCP abilitato per OAuth.
    • kilo mcp logout [name]: Rimuove le credenziali OAuth per un server MCP.
    • kilo mcp debug <name>: Esegue il debug della connessione OAuth per un server MCP.

3.4 Integrazione con Servizi Esterni (MCP)

Come OpenCode, Kilo Code CLI supporta nativamente il Model Context Protocol (MCP). Puoi utilizzare i comandi kilo mcp (descritti sopra) per aggiungere e gestire server MCP, permettendo a Kilo di interagire con API esterne, database e altri strumenti durante la generazione del codice.