> ## 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.

# Usar Pi com CometAPI

> Use este guia para configurar o Pi com CometAPI definindo a URL base, a chave de API e as opções de model ou provider.

[Pi](https://github.com/earendil-works/pi) é o projeto Pi Agent Harness. Seu pacote `@earendil-works/pi-coding-agent` fornece uma CLI interativa de agente de programação com fluxos de trabalho de arquivo, shell, edit, write, session, print, JSON, RPC e SDK. O Pi pode carregar providers personalizados de `~/.pi/agent/models.json`, para que você possa adicionar o CometAPI como entradas de provider compatíveis com OpenAI sem alterar o código-fonte do Pi.

Referências oficiais:

* [Repositório do Pi](https://github.com/earendil-works/pi)
* [Guia de início rápido do Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/quickstart.md)
* [Providers do Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md)
* [Models personalizados do Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md)
* [Uso da CLI do Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/usage.md)

<Note>
  A disponibilidade dos models muda com o tempo. Substitua `your-model-id` por um model ID disponível na [página de Models do CometAPI](/pt/overview/models).
</Note>

## Pré-requisitos

* Node.js `>=22.19.0`
* npm
* Uma conta CometAPI com uma chave de API ativa do [painel](https://www.cometapi.com/console/token)
* Pi instalado a partir do pacote npm oficial

## Entenda as permissões de runtime

O Pi é executado com as permissões do usuário e do processo que o iniciam. Inicie o Pi no diretório do projeto em que deseja que ele trabalhe, mantenha um caminho de reversão como o git e use um contêiner ou sandbox se precisar de limites mais fortes para sistema de arquivos, processos, rede ou credenciais.

## Configurar o provider

<Steps>
  <Step title="Instalar o Pi">
    Instale o Pi globalmente com npm:

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

    Confirme que a CLI está disponível:

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

  <Step title="Defina sua chave de API da CometAPI">
    Armazene sua chave de API da CometAPI na variável de ambiente `COMETAPI_KEY`:

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

    Adicione o comando de exportação ao perfil do seu shell se quiser que ele persista entre sessões de terminal. Não faça commit de chaves de API no controle de versão.
  </Step>

  <Step title="Adicione providers da CometAPI ao models.json">
    Crie `~/.pi/agent/models.json` se ele não existir. Se o arquivo já contiver providers, mescle as entradas `cometapi-responses` e `cometapi-chat` no objeto `providers` existente:

    ```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"
            }
          ]
        }
      }
    }
    ```

    Use `cometapi-responses` para modelos ou fluxos de trabalho que exigem a API OpenAI Responses. Use `cometapi-chat` para modelos compatíveis com OpenAI Chat Completions. O Pi resolve `$COMETAPI_KEY` no momento da requisição. Mantenha a chave de API no seu ambiente ou no seu próprio fluxo de gerenciamento de segredos.
  </Step>

  <Step title="Verifique ambos os providers">
    Liste os modelos que o Pi consegue ver para o provider Responses:

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

    Execute um Prompt curto de uso único com o provider Responses:

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

    Liste os modelos que o Pi consegue ver para o provider Chat Completions:

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

    Execute um Prompt curto de uso único com o 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."
    ```

    Para uso interativo, inicie o Pi no seu projeto e selecione o provider e o modelo da CometAPI com `/model`. Se você editar `models.json` durante uma sessão interativa, abra `/model` novamente para que o Pi recarregue as entradas de modelo personalizadas.
  </Step>
</Steps>

## Solução de problemas

<AccordionGroup>
  <Accordion title="Pi não mostra o modelo da CometAPI">
    Confirme que `~/.pi/agent/models.json` é um JSON válido e que cada entrada de provider está dentro do objeto `providers` de nível superior. Execute `pi --list-models cometapi-responses` ou `pi --list-models cometapi-chat` após salvar o arquivo.
  </Accordion>

  <Accordion title="Pi informa que nenhuma chave de API está disponível">
    Confirme que `COMETAPI_KEY` está definida na mesma sessão de shell que inicia o Pi. Se você usar um perfil de shell, abra um novo terminal ou recarregue o perfil antes de executar o Pi.
  </Accordion>

  <Accordion title="As solicitações falham por causa da URL base">
    Use `https://api.cometapi.com/v1` como `baseUrl` em `models.json`. Não aponte o Pi para a URL do dashboard nem omita o sufixo `/v1` para rotas compatíveis com OpenAI.
  </Accordion>

  <Accordion title="Pi falha antes de enviar uma solicitação ao modelo">
    Verifique sua versão do Node.js com `node --version`. O pacote Pi requer Node.js `>=22.19.0`.
  </Accordion>

  <Accordion title="O modelo funciona em uma rota, mas não na outra">
    Use a entrada de provider cujo campo `api` corresponde à rota compatível com seu modelo. `openai-responses` usa a API Responses, enquanto `openai-completions` usa Chat Completions.
  </Accordion>

  <Accordion title="Pi tem mais acesso do que o esperado">
    O Pi é executado com as permissões do usuário e do processo que o iniciaram. Execute o Pi dentro de um contêiner ou sandbox quando precisar de limites mais rígidos em torno de arquivos, processos, acesso à rede ou credenciais.
  </Accordion>
</AccordionGroup>

## Recursos relacionados

* [Início rápido do CometAPI](/pt/overview/quick-start)
* [Página de modelos do CometAPI](/pt/overview/models)
* [Modelos personalizados do Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md)
* [Uso da CLI do 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": "Usar Pi com CometAPI",
        "description": "Use este guia para configurar o Pi com CometAPI definindo a URL base, a chave de API e as opções de model ou provider.",
        "step": [
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-1",
            "position": 1,
            "name": "Instalar o Pi",
            "text": "Conclua a etapa Instalar o Pi no guia Usar Pi com CometAPI."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-2",
            "position": 2,
            "name": "Defina sua chave de API do CometAPI",
            "text": "Armazene sua chave de API do CometAPI na variável de ambiente ou no campo de configurações usado pela integração."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-3",
            "position": 3,
            "name": "Adicionar providers do CometAPI ao models.json",
            "text": "Conclua a etapa Adicionar providers do CometAPI ao models.json no guia Usar Pi com CometAPI."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-4",
            "position": 4,
            "name": "Verificar ambos os providers",
            "text": "Conclua a etapa Verificar ambos os providers no guia Usar Pi com CometAPI."
          }
        ]
      },
      {
        "@type": "BreadcrumbList",
        "itemListElement": [
          {
            "@type": "ListItem",
            "position": 1,
            "name": "Documentação do CometAPI",
            "item": "https://apidoc.cometapi.com/"
          },
          {
            "@type": "ListItem",
            "position": 2,
            "name": "Integrações",
            "item": "https://apidoc.cometapi.com/integrations"
          },
          {
            "@type": "ListItem",
            "position": 3,
            "name": "Usar Pi com CometAPI",
            "item": "https://apidoc.cometapi.com/integrations/pi"
          }
        ]
      }
    ]
    }
    `}
</script>