---
title: "Gli agenti in Kalka | Kalka docs"
description: "Configura il pannello IA con il tuo agente di codice o una chiave API, lavora con Pebble e con gli agenti con nome, rispondi alle sue domande, e annulla o segui quello che fa."
url: https://kalka.design/it/docs/agents
language: it
---

Il pannello IA di Kalka mette un agente accanto al canvas. Scrive HTML e CSS, il materiale di cui è fatto Kalka, quindi quello che disegna arriva come livelli normali che puoi selezionare e modificare a mano.

Gli agenti sono facoltativi: in Kalka tutto funziona anche senza.

## Aprire il pannello IA

Fai clic su **AI** in cima alla barra laterale sinistra, oppure premi Cmd J (Ctrl J). Per chiedere qualcosa su un elemento preciso, selezionalo e premi /: il pannello si apre con la selezione allegata.

_Il pannello IA che propone gli agenti di codice di questo computer o account API_

Il pannello IA prima della configurazione. Nel browser sono proposti solo account API; gli agenti di codice richiedono l’app desktop.

## Scegliere l’agente

La prima volta, Kalka propone una configurazione guidata. Puoi rilanciarla da **Impostazioni › IA e agenti › Avvia la configurazione guidata**.

### L’agente di codice sul tuo computer

Se usi già Claude Code, Codex o Gemini CLI, Kalka può eseguirlo nel pannello IA con il tuo abbonamento e il tuo modello. Funziona nell’app desktop. Kalka parla con l’agente tramite l’Agent Client Protocol (ACP) e gli presta gli strumenti del canvas.

La configurazione controlla cosa è installato e propone **Installa adattatore** quando manca un piccolo connettore. Per riferimento:

| Agente | Connettore | Accesso |
| --- | --- | --- |
| Claude Code | npm i -g @agentclientprotocol/claude-agent-acp | esegui claude, poi /login |
| Codex | npm i -g @agentclientprotocol/codex-acp | codex login |
| Gemini CLI | npm i -g @google/gemini-cli | esegui gemini, poi /auth |

**Copia il prompt di configurazione** ti dà un messaggio da incollare nel tuo agente, così installa da solo quello che gli serve. L’agente sceglie il proprio modello; quando chiede il permesso di usare uno strumento, Kalka mostra la richiesta.

Pi, un altro agente di codice, funziona allo stesso modo tramite il companion di Kalka, `@kalka/harness`.

### Una chiave API

Kalka si collega anche direttamente a un provider di modelli: OpenRouter (con una chiave o con l’accesso), Anthropic, OpenAI, Google AI, DeepSeek, Z.ai e MiniMax. Funziona anche qualsiasi servizio che parli l’API di OpenAI o di Anthropic, con il suo indirizzo e il nome del modello.

### Un modello sul tuo computer

Per un modello locale, scegli Ollama o LM Studio nella configurazione, oppure **Altro server** per qualsiasi cosa parli l’API di OpenAI, come llama.cpp. Non serve nessuna chiave se il tuo server non la chiede.

### Modelli e ruoli

In **Impostazioni › IA e agenti**, **Modelli** elenca i modelli che hai configurato e **Assegnazioni** ne sceglie uno per ogni compito: l’**Agente di design** che chatta e modifica il canvas, la **Revisione**, le **Attività rapide** e la **Visione** per leggere screenshot e immagini. Scegli il modello e il **livello di ragionamento** di un messaggio direttamente nella chat. Gli agenti di codice scelgono da soli il modello e il ragionamento.

## Pebble

Il primo agente che lavora in un documento si chiama **Pebble**. Questo nome compare sul suo cursore, nei commenti, dove puoi scrivere `@Pebble`, e nella cronologia delle versioni.

## Prima di un nuovo design, l’agente chiede

Quando chiedi qualcosa di nuovo, l’agente prima ti chiede quello che gli serve: come si chiama l’attività, a chi si rivolge la pagina, quali sezioni, quali colori usare o evitare. Le domande arrivano nel pannello IA una alla volta, ognuna con risposte suggerite da scegliere con un clic, un campo per la tua risposta e **Salta, decide l’agente**.

## Come progetta l’agente

L’agente segue un processo di design: legge il documento, nomina i suoi riferimenti, scrive un breve brief, imposta variabili, classi e componenti, organizza la pagina, poi costruisce e verifica una sezione alla volta prima di adattare il layout per telefono.

Controlla anche il suo lavoro rispetto a un elenco di abitudini che fanno sembrare un design fatto a macchina: le solite sfumature viola, le card in vetro, file di card con icone tutte uguali, una piccola etichetta sopra ogni titolo, pulsanti luminosi e altro. Quando la sua palette o la sua tipografia ne ricalca una, sceglie di nuovo.

Sono integrate sette skill, che richiami nella chat per nome: `/direction`, `/landing-page`, `/copy`, `/critique`, `/responsive`, `/polish` e `/anti-slop`.

## Guardalo lavorare

Il lavoro dell’agente compare blocco per blocco, in ordine: lo sfondo di una cornice prima del suo contenuto, dall’alto verso il basso. Ogni blocco emerge da una leggera nuvola di punti di pixel, e prima del primo livello la stessa nuvola indica dove arriverà il lavoro. Un piccolo badge con un indicatore di caricamento mostra cosa sta costruendo l’agente.

**Segui gli agenti**, il mirino in cima al pannello IA, tiene sullo schermo il lavoro dell’agente; la vista si sposta solo quando il lavoro esce dal centro dello schermo.

Se l’animazione è troppa, attiva **Riduci le animazioni degli agenti** in **Impostazioni › Generali**: i nuovi livelli compaiono allora tutti in una volta. L’impostazione di riduzione del movimento del sistema ha lo stesso effetto.

## Agenti con nome

Più agenti possono lavorare sullo stesso documento contemporaneamente. Inizia un messaggio con un nome, come `@Fern build the pricing section`, e Fern si unisce in una sua scheda mentre la chat principale va avanti. Lavorano fino a tre agenti insieme, chat principale compresa. Se un agente prova a modificare una cornice che un altro sta costruendo, gli viene detto chi la sta usando, e lui lavora altrove o aspetta.

Gli agenti con nome richiedono un modello di design collegato direttamente, con una chiave API o un gateway. Le loro conversazioni durano finché non chiudi il documento.

## Fermare, annullare e ripristinare

- **Interrompi generazione** nella casella della chat ferma una risposta.

- Sotto ogni risposta, **Annulla le modifiche** annulla quello che quella risposta ha fatto sul canvas e **Ripristina modifiche** lo riporta. **Annulla e rigenera** ci riprova.

- Anche Cmd Z annulla le modifiche degli agenti, un passo alla volta. Annullare la modifica di un agente non annulla mai quello che un altro agente, o tu, avete cambiato nel frattempo.

- Nel pannello **Commenti**, la scheda **Modifiche** elenca le modifiche di ogni agente per pagina, con **Ripristina a prima**.

## Regole e documenti di un progetto

**Istruzioni**, nella barra laterale sinistra, contiene quello che gli agenti devono sapere su questo documento: un riassunto, regole da seguire, le tue skill (richiamate come `/nome`) e documenti di riferimento (citati come `@nome`). In una cartella Kalka vengono salvati sotto `instructions/`, quindi viaggiano con il design.

## Agenti fuori da Kalka

Qualsiasi agente che parli MCP, come Claude Code nel terminale o Cursor, può lavorare anche lui sul documento aperto. Vedi [MCP e ACP](https://kalka.design/it/docs/mcp).
