> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # DevKit Agent para gerenciar kits de desenvolvimento XBOX > Como o DevKit Agent em cada kit de desenvolvimento XBOX consulta seu serviço e executa trabalhos de configuração do console, execução de títulos e operações de arquivo por meio do OpenAPI. O DevKit Agent é um processo executado em todos os XBOX Development Kits. Esse processo permite gerenciar seus kits de desenvolvimento a partir de um serviço hospedado em cenários locais e remotos. O agente envia solicitações de heartbeat ao serviço configurado em uma cadência regular e configurável, e seu serviço pode emitir trabalhos que são executados no console. Os trabalhos são operações atômicas para cenários de gerenciamento de arquivos e do console. Os cenários comuns incluem configuração do console, execução de títulos e operação de cópia de arquivos usando as ferramentas wd\*, conforme descrito [aqui](/pt-BR/tools/tools-console/console_commandlinetools/consolecommandlinetools). ## DevKit Agent O DevKit Agent é uma máquina de estado simples em sua operação. A cada 10 segundos ou imediatamente após processar um trabalho, o agente envia um heartbeat para solicitar um único trabalho ao servidor. O trabalho é então processado imediatamente, e o activeJobId é enviado de volta no próximo heartbeat. Se nenhum trabalho estiver sendo processado, o activeJobID será um GUID com todos os valores zero. O intervalo de heartbeat pode ser ajustado usando a propriedade heartbeatInterval em KitHeartbeatResponse. Os heartbeats subsequentes são enviados nesse intervalo, a menos que ele seja alterado novamente no servidor ou quando o agente for reiniciado. Após qualquer reinicialização do console, o intervalo é redefinido para o valor padrão de 10 segundos. O agente não armazena seu estado, além do último jobID processado, mas informa a data e a hora em que foi iniciado e o tempo de atividade do console. ## Traga seu próprio serviço O DevKit Agent foi projetado com base na premissa de trazer seu próprio serviço. As definições de configuração no console fornecem ao agente o URI do seu serviço. Seu servidor escuta solicitações de heartbeat do agente, inspeciona a mensagem de heartbeat para determinar o próximo trabalho apropriado para o agente executar e, em seguida, envia o trabalho ao agente. Seu servidor está no controle; o agente não executa nenhuma operação lógica que interfira no fluxo de trabalho pretendido. O Microsoft Game Development Kit (GDK) fornece o DevKitAgentAPI.yaml. É um documento compatível com OpenApi v3.0.3 que descreve o contrato entre o DevKit Agent e o seu servidor. Esse documento detalha os caminhos com suporte (por exemplo, /KitHeartbeat) e os esquemas de componentes (por exemplo, ExecuteCommandJob, KitHeartbeatResponse, FileUpload etc.). A partir do GDK de junho de 2023, o arquivo será instalado em %SDK\_ROOT%\toolKit\include\DevKitAgentAPI.yaml. O agente funcionará com qualquer implementação de serviço que siga o contrato OpenAPI. Para obter mais informações sobre o contrato OpenAPI, veja o seguinte: * [https://spec.openapis.org/oas/v3.0.3.html](https://spec.openapis.org/oas/v3.0.3.html) * [https://openapi-generator.tech/docs/usage](https://openapi-generator.tech/docs/usage) * [https://openapi-generator.tech/docs/generators/](https://openapi-generator.tech/docs/generators/) * [Documentação da API web do ASP.NET Core com Swagger / OpenAPI](https://learn.microsoft.com/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-7.0) ## Solicitação de heartbeat do agente Veja a seguir um exemplo de solicitação de heartbeat após um executeCommandJob, formatado em JSON. O heartbeat contém detalhes sobre o agente (versão do esquema, tempo de atividade etc.), o console (ipAddress, runningApplication etc.) e o status do trabalho do agente (activeJobId, lastProcessedJobResult etc.). Para ver o esquema completo, você pode carregar o DevKitAgentAPI.yaml em vários geradores, como o Swagger. ```{ theme={null} "agentSchemaVersion": "2023.10.0", "kit": { "hostname": "DevKit01", "ipAddress": "172.200.0.1", "osVersion": "10.0.25398.2258 (xb_flt_2309zn.230918-2000)", "runningApplicationId": "41336PublisherName.ExampleGame_8wekyb3d8bbwe!App", "runningApplication": { "displayName": "Example Game", "fullName": "41336PublisherName.ExampleGame", "aumids": "41336PublisherName.ExampleGame_8wekyb3d8bbwe!App" }, "uptime": 1234567890, "deviceType": "ScarlettDevkit" }, "activeJobId": "85a5cb10-cee1-4eac-865d-978746090428", "lastProcessedJobResult": { "id": "235a5dfb10-lbb5-4bad-725d-978746083564", "executeCommandJobResult": { "commandOutput": "Here are some \"quotes\"", "exitCode": 1, "processId": 1337, "job": { "commandLine": "cmd.exe /C ECHO Here are some \\\"quotes.\\\"", "workingDirectory": "d:\\", "commandLineIsScript": true, "waitForExit": true, "willReboot": true } }, "jobType": "executeCommandJob" }, "agentStartTime": "2023-04-07T23:47:13.434Z", "currentDateTime": "2023-05-09T23:47:13.434Z" } ``` ## Trabalhos Os trabalhos são operações únicas para o agente processar. Atualmente, há quatro tipos de trabalhos: * **executeCommandJob**: executa um comando no console. O conjunto completo de comandos wd\* está disponível para execução. Você pode encontrar mais informações sobre as ferramentas de linha de comando do console wd\* [aqui](/pt-BR/tools/tools-console/console_commandlinetools/consolecommandlinetools). * **downloadFilesJob**: a URL de origem de onde o arquivo será obtido. Essa URL pode ser arbitrária e oferece a mesma autenticação configurada que as chamadas de heartbeat. As chamadas são feitas via GET e não precisam usar SSL. * **uploadFilesJob**: a URL de destino para onde o arquivo será carregado. Essa URL pode ser arbitrária e oferece a mesma autenticação configurada que as chamadas de heartbeat. As chamadas são feitas via POST ou PUT e não precisam usar SSL * **cancelCurrentJob**: esse trabalho instrui o agente a cancelar o trabalho em execução no momento. > - Defina WaitForExit como false em um trabalho Execute Command para forçar uma execução do tipo "disparar e esquecer". A propriedade LastProcessedJobResult não será preenchida com nenhuma saída ou código de saída, e o agente solicitará imediatamente o próximo trabalho. ## Segurança e autenticação Ao usar o agente, projetamos um sistema que permite uma comunicação segura e autenticada para o serviço de produção e flexibilidade durante o desenvolvimento. O agente requer comunicação com o servidor por HTTPS e se autentica no servidor usando um Xtoken. Por isso, o URI do agente precisa ser configurado como uma Relying Party no Partner Center. * O HTTPS permite que o dispositivo saiba que está se comunicando com um serviço confiável, mas não permite que o serviço saiba que o dispositivo é confiável. * Os Xtokens são usados para que o serviço possa autenticar o dispositivo com a declaração Developer Device ID (ddi), a fim de identificar exclusivamente o kit de desenvolvimento. O agente passa um Xtoken gerado ao servidor no cabeçalho `XBOX-AGENT-XTOKEN` da solicitação de heartbeat. Em seguida, o servidor descriptografa e valida a assinatura do token para autenticar o agente. O servidor pode então responder com um novo trabalho ou ignorar a solicitação. Uma nova declaração foi adicionada como opção para a configuração da sua Relying Party, chamada Developer Device ID (ddi). Essa nova declaração foi criada para garantir que o dispositivo que envia heartbeats ao seu serviço seja o esperado. A declaração ddi está disponível para qualquer relying party configurada no Partner Center, mas observe que ela só será preenchida quando executada em um XBOX Developer Kit; no varejo, retornará null. A ddi retornará a XBOX Live Device ID do dispositivo, e a XBOX Live Device ID do seu DevKit está disponível no xbdiaginfo ou em Settings no shell de varejo. O exposto acima é a prática recomendada para sua implantação de produção; certificados autoassinados podem ser usados com o DevKit Agent e seu serviço, e certificados totalmente encadeados não são necessários. Além disso, durante o desenvolvimento, ao trabalhar com kits conhecidos, não seria necessário inspecionar a ddi no servidor. Para obter mais informações sobre XTokens, veja [https://developer.microsoft.com/en-us/games/xbox/docs/gdk/live-security-token-nav](https://developer.microsoft.com/en-us/games/xbox/docs/gdk/live-security-token-nav). ## Configurar o DevKit Agent Defina dois valores de configuração no console: o URI do servidor (DevkitAgentServiceUri) e a Relying Party (DevKitAgentRelyingParty) Para definir esses valores, acesse uma linha de comando do Microsoft Game Development Kit (GDK), conecte-se ao console de destino e execute os comandos a seguir. ``` C:\Program Files (x86)\Microsoft GDK\bin>xbconfig DevKitAgentServiceUri=https://myserver.mydomain.com DevKitAgentServiceUri: https://myserver.mydomain.com C:\Program Files (x86)\Microsoft GDK\bin>xbconfig DevKitAgentRelyingParty=rp://myagentRP.mydomain.com DevKitAgentRelyingParty: rp://myagentRP.mydomain.com ``` ### Iniciar e interromper o agente O agente é iniciado e interrompido automaticamente com base na presença da configuração DevKitAgentServiceUri. Para interromper o agente, execute o comando a seguir em um XBOX Command Prompt ``` C:\Program Files (x86)\Microsoft GDK\bin>xbconfig DevKitAgentServiceUri="" ``` ou envie o comando wdConfig equivalente por meio do servidor do agente: ``` wdconfig DevKitAgentServiceUri="" ``` ## Veja também [Ferramentas de linha de comando do console](/pt-BR/tools/tools-console/console_commandlinetools/consolecommandlinetools) ## Related topics - [Processo DevKit Agent em consoles XBOX](/pt-BR/tools/tools-console/devkitagent/index.md) - [Developer Home (DevHome) em kits de desenvolvimento XBOX](/pt-BR/tools/tools-console/devhome/index.md) - [Ferramenta XBOX Manager para gerenciar consoles de desenvolvimento](/pt-BR/tools/tools-console/xbom/index.md) - [Ferramentas para desenvolvedores de console XBOX (GDK)](/pt-BR/tools/tools-console/index.md) - [Integração de Parceiro XBOX para acesso e publicação](/pt-BR/home/onboarding.md)