{"meta":{"title":"Guia de depuração","intro":"Este guia aborda problemas comuns e técnicas de depuração para o SDK do Copilot em todos os idiomas com suporte.","product":"GitHub Copilot","breadcrumbs":[{"href":"/pt/copilot","title":"GitHub Copilot"},{"href":"/pt/copilot/how-tos","title":"Instruções"},{"href":"/pt/copilot/how-tos/copilot-sdk","title":"SDK do Copilot"},{"href":"/pt/copilot/how-tos/copilot-sdk/troubleshooting","title":"Solução de problemas"},{"href":"/pt/copilot/how-tos/copilot-sdk/troubleshooting/debugging","title":"Resolução de Erros"}],"documentType":"article"},"body":"# Guia de depuração\n\nEste guia aborda problemas comuns e técnicas de depuração para o SDK do Copilot em todos os idiomas com suporte.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n## Sumário\n\n* [Habilitar o log de depuração](#enable-debug-logging)\n* [Problemas comuns](#common-issues)\n* [Depuração do servidor MCP](#mcp-server-debugging)\n* [Problemas de conexão](#connection-issues)\n* [Problemas de execução da ferramenta](#tool-execution-issues)\n* [Problemas específicos da plataforma](#platform-specific-issues)\n\n## Habilitar o log de depuração\n\nA primeira etapa na depuração é habilitar o log detalhado para ver o que está acontecendo nos bastidores.\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"typescript\" data-label=\"TypeScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">TypeScript</div>\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient({\n  logLevel: \"debug\",  // Options: \"none\", \"error\", \"warning\", \"info\", \"debug\", \"all\"\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nfrom copilot import CopilotClient\n\nclient = CopilotClient(log_level=\"debug\")\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\nimport copilot \"github.com/github/copilot-sdk/go\"\n\nclient := copilot.NewClient(&copilot.ClientOptions{\n    LogLevel: \"debug\",\n})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n<!-- docs-validate: skip -->\n\n```csharp\nusing GitHub.Copilot;\nusing Microsoft.Extensions.Logging;\n\n// Using ILogger\nvar loggerFactory = LoggerFactory.Create(builder =>\n{\n    builder.SetMinimumLevel(LogLevel.Debug);\n    builder.AddConsole();\n});\n\nvar client = new CopilotClient(new CopilotClientOptions\n{\n    LogLevel = \"debug\",\n    Logger = loggerFactory.CreateLogger<CopilotClient>()\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nimport com.github.copilot.CopilotClient;\nimport com.github.copilot.rpc.*;\n\nvar client = new CopilotClient(new CopilotClientOptions()\n    .setLogLevel(\"debug\")\n);\n```\n\n</div>\n\n</div>\n\n### Diretório de log\n\nA CLI grava logs em um diretório. Você pode especificar um local personalizado:\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"typescript\" data-label=\"TypeScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">TypeScript</div>\n\n```typescript\nconst client = new CopilotClient({\n  cliArgs: [\"--log-dir\", \"/path/to/logs\"],\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\n# The Python SDK does not currently support passing extra CLI arguments.\n# Logs are written to the default location or can be configured via\n# the CLI when running in server mode.\n```\n\n> \\[!NOTE]\n> A configuração de logging do SDK do Python é limitada. Para logs avançados, execute a CLI manualmente com `--log-dir` e conecte-se por meio de `RuntimeConnection.for_uri(...)`.\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n    Connection: copilot.StdioConnection{\n        Args: []string{\"--log-dir\", \"/path/to/logs\"},\n    },\n})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nvar client = new CopilotClient(new CopilotClientOptions\n{\n    Connection = RuntimeConnection.ForStdio(args: new[] { \"--log-dir\", \"/path/to/logs\" })\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n<!-- docs-validate: skip -->\n\n```java\n// The Java SDK does not currently support passing extra CLI arguments.\n// For custom log directories, run the CLI manually with --log-dir\n// and connect via cliUrl.\n```\n\n</div>\n\n</div>\n\n## Problemas comuns\n\n### \"CLI não encontrada\" / \"Copilot: comando não encontrado\"\n\n**Cause:** A CLI do Copilot não está instalada ou não está no PATH.\n\n**Solution:**\n\n1. Instalar a CLI: [Guia de instalação](/pt/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli)\n\n2. Verifique a instalação:\n\n   ```bash\n   copilot --version\n   ```\n\n3. Ou especifique o caminho completo:\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"javascript\" data-label=\"JavaScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">JavaScript</div>\n\n```typescript\nconst client = new CopilotClient({\n  cliPath: \"/usr/local/bin/copilot\",\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nclient = CopilotClient({\"cli_path\": \"/usr/local/bin/copilot\"})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n    Connection: copilot.StdioConnection{Path: \"/usr/local/bin/copilot\"},\n})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nvar client = new CopilotClient(new CopilotClientOptions\n{\n    CliPath = \"/usr/local/bin/copilot\"\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nvar client = new CopilotClient(new CopilotClientOptions()\n    .setCliPath(\"/usr/local/bin/copilot\")\n);\n```\n\n</div>\n\n</div>\n\n### \"Não autenticado\"\n\n**Cause:** a CLI não é autenticada com GitHub.\n\n**Solution:**\n\n1. Autenticar a interface de linha de comando (CLI):\n\n   ```bash\n   copilot auth login\n   ```\n\n2. Ou forneça um token programaticamente:\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"javascript\" data-label=\"JavaScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">JavaScript</div>\n\n```typescript\nconst client = new CopilotClient({\n  gitHubToken: process.env.GITHUB_TOKEN,\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nimport os\nclient = CopilotClient({\"github_token\": os.environ.get(\"GITHUB_TOKEN\")})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n    GitHubToken: os.Getenv(\"GITHUB_TOKEN\"),\n})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nvar client = new CopilotClient(new CopilotClientOptions\n{\n    GitHubToken = Environment.GetEnvironmentVariable(\"GITHUB_TOKEN\")\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nvar client = new CopilotClient(new CopilotClientOptions()\n    .setGitHubToken(System.getenv(\"GITHUB_TOKEN\"))\n);\n```\n\n</div>\n\n</div>\n\n### \"Sessão não encontrada\"\n\n**Causa:** Tentando usar uma sessão que foi destruída ou não existe.\n\n**Solution:**\n\n1. Verifique se você não está chamando métodos após `disconnect()`:\n\n   ```typescript\n   await session.disconnect();\n   // Don't use session after this!\n   ```\n\n2. Para retomar as sessões, verifique se a ID da sessão existe:\n\n   ```typescript\n   const sessions = await client.listSessions();\n   console.log(\"Available sessions:\", sessions);\n   ```\n\n### \"Conexão recusada\" / \"ECONNREFUSED\"\n\n**Causa:** O processo do servidor da CLI falhou ou falhou ao iniciar.\n\n**Solution:**\n\n1. Verifique se a CLI é executada corretamente autônoma:\n\n   ```bash\n   copilot --server --stdio\n   ```\n\n2. Verifique se há conflitos de porta se estiver usando o modo TCP:\n\n   ```typescript\n   const client = new CopilotClient({\n     useStdio: false,\n     port: 0,  // Use random available port\n   });\n   ```\n\n## Depuração do servidor MCP\n\nOs servidores MCP (Protocolo de Contexto de Modelo) podem ser complicados de depurar. Para obter orientações completas sobre a depuração do MCP, consulte o **[Guia de depuração do servidor MCP](/pt/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging)** específico.\n\n### Lista de verificação rápida do MCP\n\n* [ ] O executável do servidor MCP existe e é executado de forma independente\n* [ ] O caminho do comando está correto (use caminhos absolutos)\n* [ ] As ferramentas estão habilitadas: `tools: [\"*\"]`\n* [ ] O servidor responde à `initialize` solicitação corretamente\n* [ ] O diretório de trabalho (`cwd`) é definido, se necessário\n\n### Testar o servidor MCP\n\nAntes de integrar com o SDK, verifique se o servidor MCP funciona:\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}' | /path/to/your/mcp-server\n```\n\nConsulte [Guia de depuração do servidor MCP](/pt/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) para obter uma solução de problemas detalhada.\n\n## Problemas de conexão\n\n### modo stdio vs TCP\n\nO SDK dá suporte a dois modos de transporte:\n\n| Modo               | Description                                                          | Caso de uso                           |\n| ------------------ | -------------------------------------------------------------------- | ------------------------------------- |\n| **Stdio** (padrão) | A CLI é executada como subprocesso, comunica-se por meio de pipes    | Desenvolvimento local, processo único |\n| **TCP**            | A CLI é executada separadamente, comunica-se por meio do soquete TCP | Vários clientes, CLI remota           |\n\n**Modo stdio (padrão):**\n\n```typescript\nconst client = new CopilotClient({\n  useStdio: true,  // This is the default\n});\n```\n\n**Modo TCP:**\n\n```typescript\nconst client = new CopilotClient({\n  useStdio: false,\n  port: 8080,  // Or 0 for random port\n});\n```\n\n**Conecte-se ao servidor existente:**\n\n```typescript\nconst client = new CopilotClient({\n  cliUrl: \"localhost:8080\",  // Connect to running server\n});\n```\n\n### Diagnosticando falhas de conexão\n\n1. **Verifique o estado do cliente:**\n\n   ```typescript\n   console.log(\"Connection state:\", client.getState());\n   // Should be \"connected\" after start()\n   ```\n\n2. **Ouça as alterações de estado:**\n\n   ```typescript\n   client.on(\"stateChange\", (state) => {\n     console.log(\"State changed to:\", state);\n   });\n   ```\n\n3. **Verifique se o processo da CLI está em execução:**\n\n   ```bash\n   # Check for copilot processes\n   ps aux | grep copilot\n   ```\n\n## Problemas de execução da ferramenta\n\n### Ferramenta personalizada não está sendo chamada\n\n1. **Verificar o registro da ferramenta:**\n\n   ```typescript\n   const session = await client.createSession({\n     tools: [myTool],\n   });\n\n   // Check registered tools\n   console.log(\"Registered tools:\", session.getTools?.());\n   ```\n\n2. **Verificar se o esquema da ferramenta é um esquema JSON válido:**\n\n   ```typescript\n   const myTool = {\n     name: \"get_weather\",\n     description: \"Get weather for a location\",\n     parameters: {\n       type: \"object\",\n       properties: {\n         location: { type: \"string\", description: \"City name\" },\n       },\n       required: [\"location\"],\n     },\n     handler: async (args) => {\n       return { temperature: 72 };\n     },\n   };\n   ```\n\n3. **Verifique se o manipulador retorna o resultado válido:**\n\n   ```typescript\n   handler: async (args) => {\n     // Must return something JSON-serializable\n     return { success: true, data: \"result\" };\n     \n     // Don't return undefined or non-serializable objects\n   }\n   ```\n\n### Erros de ferramenta que não são exibidos\n\nInscreva-se em eventos de erro:\n\n```typescript\nsession.on(\"tool.execution_error\", (event) => {\n  console.error(\"Tool error:\", event.data);\n});\n\nsession.on(\"error\", (event) => {\n  console.error(\"Session error:\", event.data);\n});\n```\n\n## Problemas específicos da plataforma\n\n### Windows\n\n1. **Separadores de caminho:** use strings brutas ou barras:\n\n   ```csharp\n   CliPath = @\"C:\\Program Files\\GitHub\\copilot.exe\"\n   // or\n   CliPath = \"C:/Program Files/GitHub/copilot.exe\"\n   ```\n\n2. **Resolução PATHEXT:** O SDK lida com isso automaticamente, mas se os problemas persistirem:\n\n   ```csharp\n   // Explicitly specify .exe\n   Command = \"myserver.exe\"  // Not just \"myserver\"\n   ```\n\n3. **Codificação do console:** Certifique-se de UTF-8 para tratamento JSON adequado:\n\n   ```csharp\n   Console.OutputEncoding = System.Text.Encoding.UTF8;\n   ```\n\n### macOS\n\n1. **Problemas do gatekeeper:** Se a CLI estiver bloqueada:\n\n   ```bash\n   xattr -d com.apple.quarantine /path/to/copilot\n   ```\n\n2. **Problemas de PATH em aplicativos de GUI:** Os aplicativos de GUI podem não herdar o PATH do shell:\n\n   ```typescript\n   const client = new CopilotClient({\n     cliPath: \"/opt/homebrew/bin/copilot\",  // Full path\n   });\n   ```\n\n### Linux\n\n1. **Problemas de permissão:**\n\n   ```bash\n   chmod +x /path/to/copilot\n   ```\n\n2. **Bibliotecas ausentes:** Verifique se há bibliotecas compartilhadas necessárias:\n\n   ```bash\n   ldd /path/to/copilot\n   ```\n\n## Obtendo ajuda\n\nSe você ainda estiver preso:\n\n1. **Coletar informações de depuração:**\n   * Versão do SDK\n   * Versão da CLI (`copilot --version`)\n   * Sistema operacional\n   * Registros de depuração\n   * Código de reprodução mínimo\n\n2. **Pesquisar problemas existentes:**[problemas do GitHub](https://github.com/github/copilot-sdk/issues)\n\n3. **Abrir um novo problema** com as informações coletadas\n\n## Consulte também\n\n* [Crie seu primeiro aplicativo com tecnologia do Copilot](/pt/copilot/how-tos/copilot-sdk/getting-started)\n* [Usando servidores MCP com o SDK do GitHub Copilot](/pt/copilot/how-tos/copilot-sdk/features/mcp) - Configuração e instalação do MCP\n* [Guia de depuração do servidor MCP](/pt/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) – Solução de problemas detalhada do MCP\n* [Referência da API](https://github.com/github/copilot-sdk)"}