{"meta":{"title":"Compatibilidade do SDK e da CLI","intro":"Este documento detalha quais recursos da CLI do Copilot estão disponíveis por meio do SDK e quais são exclusivos da CLI.","product":"GitHub Copilot","breadcrumbs":[{"href":"/pt/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/pt/enterprise-cloud@latest/copilot/how-tos","title":"Instruções"},{"href":"/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk","title":"SDK do Copilot"},{"href":"/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting","title":"Solução de problemas"},{"href":"/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/compatibility","title":"Compatibility"}],"documentType":"article"},"body":"# Compatibilidade do SDK e da CLI\n\nEste documento detalha quais recursos da CLI do Copilot estão disponíveis por meio do SDK e quais são exclusivos da CLI.\n\n\n\n\n\n## Overview\n\nO SDK do Copilot se comunica com a CLI por meio do protocolo JSON-RPC. Os recursos devem ser explicitamente expostos por meio desse protocolo para estarem disponíveis no SDK. Muitos recursos interativos da CLI são específicos do terminal e não estão disponíveis programaticamente.\n\n## Comparação de funcionalidades\n\n### ✅ Disponível no SDK\n\n| Característica | Método SDK | Notes |\n| ---------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| **Gerenciamento de Sessão** | | |\n| | | |\n| Criar sessão | `createSession()` | Suporte completo à configuração |\n| Retomar sessão | `resumeSession()` | Com espaços de trabalho de sessão infinitos |\n| Desconectar sessão | `disconnect()` | Liberar recursos na memória |\n| Destruir sessão *(preterida)* | `destroy()` | Use `disconnect()` em vez disso |\n| Excluir sessão | `deleteSession()` | Remover do armazenamento |\n| Listar sessões | `listSessions()` | Todas as sessões armazenadas |\n| Obter a última sessão | `getLastSessionId()` | Para retomar rapidamente |\n| Obter sessão em primeiro plano | `getForegroundSessionId()` | Coordenação de várias sessões |\n| Configurar sessão em primeiro plano | `setForegroundSessionId()` | Coordenação de várias sessões |\n| **Messaging** | | |\n| | | |\n| Enviar mensagem | `send()` | Com anexos |\n| Enviar e aguardar | `sendAndWait()` | Bloqueia até a conclusão |\n| Direção (modo imediato) | `send({ mode: \"immediate\" })` | Injetar no meio da rotação sem anular |\n| Fila (modo de enfileiramento) | `send({ mode: \"enqueue\" })` | Buffer para processamento sequencial (padrão) |\n| Anexos de arquivo | `send({ attachments: [{ type: \"file\", path }] })` | Imagens codificadas automaticamente e redimensionadas |\n| Anexos de diretório | `send({ attachments: [{ type: \"directory\", path }] })` | Anexar contexto de diretório |\n| Obter histórico | `getEvents()` | Todos os eventos de sessão |\n| Anular | `abort()` | Cancelar solicitação de disponibilização de versão piloto |\n| **Ferramentas** | | |\n| | | |\n| Registrar ferramentas personalizadas | `registerTools()` | Suporte completo ao esquema JSON |\n| Controle de permissão da ferramenta | Gancho `onPreToolUse` | Permitir/negar/perguntar |\n| Modificação do resultado da ferramenta | Gancho `onPostToolUse` | Transformar resultados |\n| Ferramentas disponíveis/excluídas | | |\n| `availableTools`, `excludedTools` configuração | Filtrar ferramentas | |\n| **Modelos** | | |\n| | | |\n| Listar modelos | `listModels()` | Com funcionalidades, cobrança, política |\n| Definir modelo (na criação) | | |\n| `model` na configuração da sessão | Por sessão | |\n| Modelo de switch (durante a sessão) | `session.setModel()` | Também via `session.rpc.model.switchTo()` |\n| Obter o modelo atual | `session.rpc.model.getCurrent()` | Consultar o modelo ativo |\n| Esforço de raciocínio | | |\n| `reasoningEffort` Configuração | Para modelos com suporte | |\n| **Modo de agente** | | |\n| | | |\n| Obter o modo atual | `session.rpc.mode.get()` | Retorna o modo atual |\n| Configurar modo | `session.rpc.mode.set()` | Alternar entre os modos |\n| **Gerenciamento de Planos** | | |\n| | | |\n| Plano de leitura | `session.rpc.plan.read()` | Obter o conteúdo e o caminho de plan.md |\n| Plano de atualização | `session.rpc.plan.update()` | Escrever conteúdo do plan.md |\n| Excluir plano | `session.rpc.plan.delete()` | Remover plan.md |\n| **Arquivos do Workspace**. | | |\n| | | |\n| Listar arquivos do espaço de trabalho | `session.rpc.workspace.listFiles()` | Arquivos na área de trabalho da sessão |\n| Ler arquivo do espaço de trabalho | `session.rpc.workspace.readFile()` | Ler o conteúdo do arquivo |\n| Criar arquivo de workspace | `session.rpc.workspace.createFile()` | Criar arquivo no workspace |\n| **Autenticação** | | |\n| | | |\n| Obter o status de autenticação | `getAuthStatus()` | Verificar o estado de logon |\n| Usar token | | |\n| Opção `gitHubToken` | Autenticação programática | |\n| **Conectividade** | | |\n| | | |\n| Ping | `client.ping()` | Verificação de integridade com carimbo de data e hora do servidor |\n| Obter o status do servidor | `client.getStatus()` | Informações sobre a versão do protocolo e o servidor |\n| **Servidores MCP** | | |\n| | | |\n| Servidores locais/stdio | | |\n| `mcpServers` Configuração | Criar processos | |\n| HTTP/SSE remoto | | |\n| `mcpServers` Configuração | Conectar-se a serviços | |\n| **Hooks** | | |\n| | | |\n| Uso de pré-ferramenta | `onPreToolUse` | Permissão, modificar args |\n| Após o uso da ferramenta (sucesso) | `onPostToolUse` | Modificar resultados |\n| Após o uso da ferramenta (falha) | `onPostToolUseFailure` | Monitorar chamadas de ferramentas com falha, injetar orientações para nova tentativa |\n| Solicitação do usuário | `onUserPromptSubmitted` | Modificar prompts |\n| Início/término da sessão | | |\n| `onSessionStart`, `onSessionEnd` | Ciclo de vida com origem/motivo | |\n| Tratamento de erros | `onErrorOccurred` | Manipulação personalizada |\n| **Eventos** | | |\n| | | |\n| Todos os eventos de sessão | | |\n| `on()`, `once()` | Mais de 40 tipos de evento | |\n| Streaming | `streaming: true` | Eventos delta |\n| **Configuração da Sessão** | | |\n| | | |\n| Agentes personalizados | | |\n| `customAgents` Configuração | Definir agentes especializados | |\n| Mensagem do sistema | | |\n| `systemMessage` Configuração | Acrescentar ou substituir | |\n| Provedor personalizado | | |\n| `provider` Configuração | Suporte ao BYOK | |\n| Sessões infinitas | | |\n| `infiniteSessions` Configuração | Compactação automática | |\n| Manipulador de permissões | `onPermissionRequest` | Aprovar/negar solicitações; opcionalmente, anexar `decisionContext` para telemetria de aprovação automática |\n| Manipulador de entrada do usuário | `onUserInputRequest` | Manipular ask\\_user |\n| Habilidades | | |\n| `skillDirectories` Configuração | Habilidades personalizadas | |\n| Habilidades desabilitadas | | |\n| `disabledSkills` Configuração | Desabilitar habilidades específicas | |\n| Diretório de configuração | | |\n| `configDir` Configuração | Substituir a localização de config padrão | |\n| Nome do cliente | | |\n| `clientName` Configuração | Identificar o aplicativo no User-Agent | |\n| Diretório de trabalho | | |\n| `workingDirectory` Configuração | Definir o cwd da sessão | |\n| Diretórios adicionais | | |\n| `additionalDirectories` Configuração | Permitir acesso à sessão além do diretório de trabalho; fornecer novamente ao retomar | |\n| **Experimental** | | |\n| | | |\n| Gerenciamento de agentes | `session.rpc.agent.*` | Listar, selecionar, deselecionar, obter o agente atual |\n| Modo de frota | `session.rpc.fleet.start()` | Execução paralela de sub-agente; ver [Modo de frota](/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/fleet-mode) |\n| Compactação manual | `session.rpc.history.compact()` | Acionar compactação sob demanda |\n| Limpeza de contexto | `session.rpc.history.clearContext()` | Substituir o contexto da conversa em uma ferramenta de terminal |\n| Truncamento de histórico | `session.rpc.history.truncate()` | Remover eventos de um ponto em diante |\n| Bifurcação de sessão | `server.rpc.sessions.fork()` | Criar uma bifurcação de uma sessão a partir de um ponto do histórico |\n\n### ❌ Não disponível no SDK (somente CLI)\n\n| Característica | Comando/opção da CLI | Reason |\n| ------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------- |\n| **Exportação de sessão** | | |\n| | | |\n| Exportar para arquivo | | |\n| `--share`, `/share` | Não está no protocolo | |\n| Exportar como gist | | |\n| `--share-gist`, `/share gist` | Não está no protocolo | |\n| **Interface do usuário interativa** | | |\n| | | |\n| Comandos de barra \"/\" | | |\n| `/help`, `/clear`, `/exit`, etc. | Somente TUI | |\n| Caixa de diálogo seletor de agente | `/agent` | Interface do usuário interativa |\n| Caixa de diálogo do modo Diff | `/diff` | Interface do usuário interativa |\n| Caixa de diálogo de feedback | `/feedback` | Interface do usuário interativa |\n| Seletor de tema | `/theme` | Interface do usuário do terminal |\n| Seletor de modelo | `/model` | Interface do usuário interativa (use o SDK `setModel()` em vez disso) |\n| Copiar para a área de transferência | `/copy` | Específico do terminal |\n| Gerenciamento de contexto | `/context` | Interface do usuário interativa |\n| **Pesquisa & Histórico** | | |\n| | | |\n| Pesquisa profunda | `/research` | Fluxo de trabalho TUI com pesquisa na Web |\n| Ferramentas de histórico de sessão | `/chronicle` | Reunião, dicas, melhorar, reindexar |\n| Recursos do terminal | | |\n| | | |\n| Saída de cor | `--no-color` | Específico do terminal |\n| Modo de leitor de tela | `--screen-reader` | Accessibility |\n| Renderização de diff avançado | `--plain-diff` | Renderização de terminal |\n| Faixa de inicialização | `--banner` | Elemento visual |\n| Modo de transmissão | `/streamer-mode` | Modo de exibição TUI |\n| Buffer de tela alternativo | | |\n| `--alt-screen`, `--no-alt-screen` | Renderização de terminal | |\n| Suporte ao mouse | | |\n| `--mouse`, `--no-mouse` | Entrada do terminal | |\n| **Atalhos de caminho/permissão** | | |\n| | | |\n| Permitir todos os caminhos | `--allow-all-paths` | Usar o manipulador de permissões |\n| Permitir todas as URLs | `--allow-all-urls` | Usar o manipulador de permissões |\n| Permitir todas as permissões | | |\n| `--yolo`, `--allow-all`, `/allow-all` | Usar o manipulador de permissões | |\n| Permissões granulares de ferramenta | | |\n| `--allow-tool`, `--deny-tool` | Usar o gancho `onPreToolUse` | |\n| Controle de acesso à URL | | |\n| `--allow-url`, `--deny-url` | Usar o manipulador de permissões | |\n| Redefinir ferramentas permitidas | `/reset-allowed-tools` | Comando TUI |\n| **Gerenciamento de Diretório** | | |\n| | | |\n| Adicionar diretório | | |\n| `/add-dir`, `--add-dir` | Configurar na sessão | |\n| Listar diretórios | `/list-dirs` | Comando TUI |\n| Alterar diretório | `/cwd` | Comando TUI |\n| **Gerenciamento de Plug-in/MCP** | | |\n| | | |\n| Comandos de plugin | `/plugin` | Gerenciamento interativo |\n| Gerenciamento de servidor MCP | `/mcp` | Interface do usuário interativa |\n| **Gestão de Contas** | | |\n| | | |\n| Fluxo de logon | | |\n| `/login`, `copilot auth login` | Fluxo do dispositivo OAuth | |\n| Sair | | |\n| `/logout`, `copilot auth logout` | CLI direta | |\n| Informações do usuário | `/user` | Comando TUI |\n| **Operações de sessão** | | |\n| | | |\n| Limpar conversa | `/clear` | Somente TUI |\n| Visão em planta | `/plan` | Somente TUI (use o SDK `session.rpc.plan.*` em vez disso) |\n| Gerenciamento de sessão | | |\n| `/session`, `/resume`, `/rename` | Fluxo de trabalho TUI | |\n| Modo de gerenciamento de frota (interativo) | `/fleet` | Somente TUI (use o SDK `session.rpc.fleet.start()` em vez disso) |\n| **Gerenciamento de habilidades** | | |\n| | | |\n| Gerenciar habilidades | `/skills` | Interface do usuário interativa |\n| **Gerenciamento de Tarefas** | | |\n| | | |\n| Exibir tarefas em segundo plano | `/tasks` | Comando TUI |\n| **Uso e Estatísticas** | | |\n| | | |\n| Uso de token | `/usage` | Assinar eventos de uso |\n| **Revisão de código** | | |\n| | | |\n| Revisar alterações | `/review` | Comando TUI |\n| **Delegação** | | |\n| | | |\n| Delegar ao PR | `/delegate` | Fluxo de trabalho TUI |\n| **Instalação do terminal** | | |\n| | | |\n| Integração do Shell | `/terminal-setup` | Específico do shell |\n| **Desenvolvimento** | | |\n| | | |\n| Alternar experimental | | |\n| `/experimental`, `--experimental` | Sinalizador de runtime | |\n| Controle de instruções personalizadas | `--no-custom-instructions` | Sinalizador da CLI |\n| Diagnosticar sessão | `/diagnose` | Comando TUI |\n| Exibir/gerenciar instruções | `/instructions` | Comando TUI |\n| Coletar logs de depuração | `/collect-debug-logs` | Ferramenta de diagnóstico |\n| Reindexar espaço de trabalho | `/reindex` | Comando TUI |\n| Integração de IDE | `/ide` | Fluxo de trabalho específico do IDE |\n| **Modo não interativo** | | |\n| | | |\n| Modo de prompt | | |\n| `-p`, `--prompt` | Execução de tiro único | |\n| Prompt interativo | | |\n| `-i`, `--interactive` | Execução automática e depois interativa | |\n| Saída silenciosa | | |\n| `-s`, `--silent` | Amigável ao script | |\n| Continuar sessão | `--continue` | Retomar o mais recente |\n| Seleção do agente | `--agent ` | Sinalizador da CLI |\n\n## Soluções alternativas\n\n### Modo de frota\n\nO modo de frota está disponível por meio de `session.rpc.fleet.start()` para aplicativos com SDK que desejam que o runtime acione subagentes em paralelo para atingir um objetivo mais amplo. Use-o quando subtarefas independentes puderem ser executadas simultaneamente e, em seguida, ser resumidas pela sessão principal. Para obter um guia completo, consulte [Modo de frota](/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/fleet-mode).\n\n### Exportação de sessão\n\nA `--share` opção não está disponível por meio do SDK. Soluções alternativas:\n\n1. **Coletar eventos manualmente** – assine eventos de sessão e crie sua própria exportação:\n\n ```typescript\n const events: SessionEvent[] = [];\n session.on((event) => events.push(event));\n // ... after conversation ...\n const messages = await session.getEvents();\n // Format as markdown yourself\n ```\n\n2. **Use a CLI diretamente para exportação** - Execute a CLI com `--share` para exportações pontuais.\n\n### Controle de permissão\n\nO SDK usa um modelo **de permissões que nega por padrão**. Todas as solicitações de permissão (gravações de arquivo, comandos de shell, buscas de URL etc.) são negadas, a menos que seu aplicativo forneça um `onPermissionRequest` manipulador.\n\nEm vez de `--allow-all-paths` ou `--yolo`, use o manipulador de permissões:\n\n```typescript\nconst session = await client.createSession({\n onPermissionRequest: approveAll,\n});\n```\n\n### Acompanhamento de uso de token\n\nEm vez de `/usage`, assine eventos de uso:\n\n```typescript\nsession.on(\"assistant.usage\", (event) => {\n console.log(\"Tokens used:\", {\n input: event.data.inputTokens,\n output: event.data.outputTokens,\n });\n});\n```\n\n### Compactação de contexto\n\nEm vez de `/compact`, configure a compactação automática ou acione-a manualmente:\n\n```typescript\n// Automatic compaction via config\nconst session = await client.createSession({\n infiniteSessions: {\n enabled: true,\n backgroundCompactionThreshold: 0.80, // Start background compaction at 80% context utilization\n bufferExhaustionThreshold: 0.95, // Block and compact at 95% context utilization\n },\n});\n\n// Manual compaction (experimental)\nconst result = await session.rpc.history.compact();\nconsole.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);\n```\n\n> \\[!NOTE]\n> Os limites são taxas de utilização de contexto (0,0-1,0), não contagens absolutas de token.\n\n### Gerenciamento de Planos\n\nLer e escrever planos de sessão de forma programática:\n\n```typescript\n// Read the current plan\nconst plan = await session.rpc.plan.read();\nif (plan.exists) {\n console.log(plan.content);\n}\n\n// Update the plan\nawait session.rpc.plan.update({ content: \"# My Plan\\n- Step 1\\n- Step 2\" });\n\n// Delete the plan\nawait session.rpc.plan.delete();\n```\n\n### Direção de mensagem\n\nInjetar uma mensagem no turno atual do LLM sem interromper:\n\n```typescript\n// Steer the agent mid-turn\nawait session.send({ prompt: \"Focus on error handling first\", mode: \"immediate\" });\n\n// Default: enqueue for next turn\nawait session.send({ prompt: \"Next, add tests\" });\n```\n\n## Limitações de protocolo\n\nO SDK só pode acessar recursos expostos por meio do protocolo JSON-RPC da CLI. Se você precisar de um recurso da CLI que não esteja disponível:\n\n1. **Verificar se há alternativas** – muitos recursos têm equivalentes do SDK (confira as soluções alternativas acima)\n2. **Usar a CLI diretamente** – para operações pontuais, invoque a CLI\n3. **Solicitar o recurso** – Abrir um problema para solicitar suporte ao protocolo\n\n## Compatibilidade entre versões\n\n| Intervalo do protocolo do SDK | Versão do protocolo CLI | Compatibility |\n| ----------------------------- | ----------------------- | ---------------------------------------- |\n| v2–v3 | v3 | Suporte completo |\n| v2–v3 | v2 | Suportado por adaptadores automáticos v2 |\n\nO SDK negocia versões de protocolo com a CLI na inicialização. O SDK dá suporte às versões de protocolo 2 a 3. Ao se conectar a um servidor CLI v2, o SDK adapta automaticamente as mensagens `tool.call` e `permission.request` ao modelo de evento v3, sem necessidade de alterar o código.\n\nVerifique as versões em tempo de execução:\n\n```typescript\nconst status = await client.getStatus();\nconsole.log(\"Protocol version:\", status.protocolVersion);\n```\n\n## Consulte também\n\n* [Crie seu primeiro aplicativo com tecnologia do Copilot](/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/getting-started)\n* [Ganchos de sessão](/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/hooks-overview)\n* [Usando servidores MCP com o SDK do GitHub Copilot](/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/mcp)\n* [Guia de depuração](/pt/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/debugging)"}