> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usare Pi con CometAPI

> Usa questa guida per configurare Pi con CometAPI impostando l'URL di base, la chiave API e le opzioni di model o provider.

[Pi](https://github.com/earendil-works/pi) è il progetto Pi Agent Harness. Il pacchetto `@earendil-works/pi-coding-agent` fornisce una CLI interattiva per agenti di coding con workflow per file, shell, modifica, scrittura, sessione, stampa, JSON, RPC e SDK. Pi può caricare provider personalizzati da `~/.pi/agent/models.json`, quindi puoi aggiungere CometAPI come voci di provider compatibili con OpenAI senza modificare il codice sorgente di Pi.

Riferimenti ufficiali:

* [Repository di Pi](https://github.com/earendil-works/pi)
* [Guida rapida di Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/quickstart.md)
* [Provider di Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md)
* [Modelli personalizzati di Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md)
* [Utilizzo della CLI di Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/usage.md)

<Note>
  La disponibilità dei modelli cambia nel tempo. Sostituisci `your-model-id` con un model ID disponibile dalla [pagina dei modelli di CometAPI](/it/overview/models).
</Note>

## Prerequisiti

* Node.js `>=22.19.0`
* npm
* Un account CometAPI con una chiave API attiva dalla [dashboard](https://www.cometapi.com/console/token)
* Pi installato dal pacchetto npm ufficiale

## Comprendere i permessi di runtime

Pi viene eseguito con i permessi dell'utente e del processo che lo avvia. Avvia Pi nella directory del progetto su cui vuoi farlo lavorare, mantieni un percorso di rollback come git e usa un container o una sandbox se hai bisogno di limiti più rigorosi per filesystem, processi, rete o credenziali.

## Configura il provider

<Steps>
  <Step title="Installa Pi">
    Installa Pi globalmente con npm:

    ```bash theme={null}
    npm install -g --ignore-scripts @earendil-works/pi-coding-agent
    ```

    Conferma che la CLI sia disponibile:

    ```bash theme={null}
    pi --version
    ```
  </Step>

  <Step title="Imposta la tua chiave API CometAPI">
    Memorizza la tua chiave API CometAPI nella variabile d'ambiente `COMETAPI_KEY`:

    ```bash theme={null}
    read -rsp "CometAPI API key: " COMETAPI_KEY
    printf '\n'
    export COMETAPI_KEY
    ```

    Aggiungi il comando di export al profilo della tua shell se vuoi che persista tra le sessioni del terminale. Non salvare le chiavi API nel controllo di versione.
  </Step>

  <Step title="Aggiungi i provider CometAPI a models.json">
    Crea `~/.pi/agent/models.json` se non esiste. Se il file contiene già dei provider, unisci le voci `cometapi-responses` e `cometapi-chat` nell'oggetto `providers` esistente:

    ```json theme={null}
    {
      "providers": {
        "cometapi-responses": {
          "name": "CometAPI Responses",
          "baseUrl": "https://api.cometapi.com/v1",
          "api": "openai-responses",
          "apiKey": "$COMETAPI_KEY",
          "models": [
            {
              "id": "your-model-id",
              "name": "CometAPI Responses model"
            }
          ]
        },
        "cometapi-chat": {
          "name": "CometAPI Chat Completions",
          "baseUrl": "https://api.cometapi.com/v1",
          "api": "openai-completions",
          "apiKey": "$COMETAPI_KEY",
          "models": [
            {
              "id": "your-model-id",
              "name": "CometAPI Chat model"
            }
          ]
        }
      }
    }
    ```

    Usa `cometapi-responses` per i modelli o i workflow che richiedono l'API OpenAI Responses. Usa `cometapi-chat` per i modelli compatibili con OpenAI Chat Completions. Pi risolve `$COMETAPI_KEY` al momento della richiesta. Mantieni la chiave API nel tuo ambiente o nel tuo workflow di gestione dei segreti.
  </Step>

  <Step title="Verifica entrambi i provider">
    Elenca i modelli che Pi può vedere per il provider Responses:

    ```bash theme={null}
    pi --list-models cometapi-responses
    ```

    Esegui un breve prompt one-shot con il provider Responses:

    ```bash theme={null}
    pi --provider cometapi-responses --model your-model-id -p "Reply with one short sentence confirming the Responses connection."
    ```

    Elenca i modelli che Pi può vedere per il provider Chat Completions:

    ```bash theme={null}
    pi --list-models cometapi-chat
    ```

    Esegui un breve prompt one-shot con il provider Chat Completions:

    ```bash theme={null}
    pi --provider cometapi-chat --model your-model-id -p "Reply with one short sentence confirming the Chat Completions connection."
    ```

    Per l'uso interattivo, avvia Pi nel tuo progetto e seleziona il provider e il modello CometAPI con `/model`. Se modifichi `models.json` durante una sessione interattiva, apri di nuovo `/model` in modo che Pi ricarichi le voci dei modelli personalizzati.
  </Step>
</Steps>

## Risoluzione dei problemi

<AccordionGroup>
  <Accordion title="Pi non mostra il modello CometAPI">
    Verifica che `~/.pi/agent/models.json` sia JSON valido e che ogni voce provider si trovi all'interno dell'oggetto `providers` di primo livello. Esegui `pi --list-models cometapi-responses` oppure `pi --list-models cometapi-chat` dopo aver salvato il file.
  </Accordion>

  <Accordion title="Pi segnala che non è disponibile alcuna API key">
    Verifica che `COMETAPI_KEY` sia impostata nella stessa sessione della shell che avvia Pi. Se usi un profilo della shell, apri un nuovo terminale oppure ricarica il profilo prima di eseguire Pi.
  </Accordion>

  <Accordion title="Le richieste non riescono a causa della base URL">
    Usa `https://api.cometapi.com/v1` come `baseUrl` in `models.json`. Non puntare Pi all'URL della dashboard e non omettere il suffisso `/v1` per le route compatibili con OpenAI.
  </Accordion>

  <Accordion title="Pi non riesce prima di inviare una richiesta al modello">
    Controlla la tua versione di Node.js con `node --version`. Il pacchetto Pi richiede Node.js `>=22.19.0`.
  </Accordion>

  <Accordion title="Il modello funziona su una route ma non sull'altra">
    Usa la voce provider il cui campo `api` corrisponde alla route supportata dal tuo modello. `openai-responses` usa l'API Responses, mentre `openai-completions` usa Chat Completions.
  </Accordion>

  <Accordion title="Pi ha più accesso del previsto">
    Pi viene eseguito con i permessi dell'utente e del processo che lo hanno avviato. Esegui Pi all'interno di un container o di una sandbox quando hai bisogno di limiti più rigidi su file, processi, accesso alla rete o credenziali.
  </Accordion>
</AccordionGroup>

## Risorse correlate

* [Guida rapida di CometAPI](/it/overview/quick-start)
* [Pagina Models di CometAPI](/it/overview/models)
* [Modelli personalizzati di Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md)
* [Utilizzo della CLI di Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/usage.md)

<script type="application/ld+json">
  {`
    {
    "@context": "https://schema.org",
    "@graph": [
      {
        "@type": "HowTo",
        "@id": "https://apidoc.cometapi.com/integrations/pi#howto",
        "name": "Usare Pi con CometAPI",
        "description": "Usa questa guida per configurare Pi con CometAPI impostando l'URL di base, la chiave API e le opzioni del model o del provider.",
        "step": [
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-1",
            "position": 1,
            "name": "Installare Pi",
            "text": "Completa il passaggio Installare Pi nella guida Usare Pi con CometAPI."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-2",
            "position": 2,
            "name": "Imposta la tua chiave API CometAPI",
            "text": "Memorizza la tua chiave API CometAPI nella variabile d'ambiente o nel campo delle impostazioni usato dall'integrazione."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-3",
            "position": 3,
            "name": "Aggiungere provider CometAPI a models.json",
            "text": "Completa il passaggio Aggiungere provider CometAPI a models.json nella guida Usare Pi con CometAPI."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-4",
            "position": 4,
            "name": "Verificare entrambi i provider",
            "text": "Completa il passaggio Verificare entrambi i provider nella guida Usare Pi con CometAPI."
          }
        ]
      },
      {
        "@type": "BreadcrumbList",
        "itemListElement": [
          {
            "@type": "ListItem",
            "position": 1,
            "name": "Documentazione CometAPI",
            "item": "https://apidoc.cometapi.com/"
          },
          {
            "@type": "ListItem",
            "position": 2,
            "name": "Integrazioni",
            "item": "https://apidoc.cometapi.com/integrations"
          },
          {
            "@type": "ListItem",
            "position": 3,
            "name": "Usare Pi con CometAPI",
            "item": "https://apidoc.cometapi.com/integrations/pi"
          }
        ]
      }
    ]
    }
    `}
</script>