> ## 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 for managing XBOX development kits

> How the DevKit Agent on every XBOX dev kit polls your service and executes jobs for console configuration, title execution, and file operations via OpenAPI.

The DevKit Agent is a process that runs on every XBOX Development Kit. This process enables you to manage your dev kits from a hosted service for local and remote scenarios. The agent sends heartbeat request to the configured service at a regular and configurable cadence and your service can issue jobs which are executed on the console. Jobs are atomic operations for file and console management scenarios. Common scenarios include console configuration, title execution, and file copy operation using wd\* tools as described [here](/tools/tools-console/console_commandlinetools/consolecommandlinetools).

## DevKit Agent

The DevKit Agent is a simple state machine in its operation. Every 10 seconds or immediately after processing a job, the agent sends a heartbeat to request a single job from the server. The job is then immediately processed and activeJobId is sent back in the next heartbeat. If no job is being processed, activeJobID is an all-zero GUID.

The heartbeat interval can be adjusted by using the heartbeatInterval property on the KitHeartbeatResponse. Subsequent heartbeats are sent on that interval unless it's changed again on the server or when the agent restarts. After any console restart, the interval resets to a default value of 10 seconds.

<Note>The agent doesn't store its state, beyond the last processed jobID, but it does report the date and time of when it was started and the uptime of the console.</Note>

## Bring your own service

The DevKit Agent is designed around the premise of bringing your own service. Configuration settings on the console provide the agent with the URI for your service. Your server listens for heartbeat requests from the agent, inspects the heartbeat message to determine the next appropriate job for the agent to run, and then sends the job to the agent. Your server is in control, the agent doesn't perform any logic operations to interfere with your intended workflow.

The Microsoft Game Development Kit (GDK) provides DevKitAgentAPI.yaml. It's an OpenApi v3.0.3 compliant document that describes the contract between the DevKit Agent and your server. This document details for supported paths (for example, /KitHeartbeat) and component schemas (for example,  ExecuteCommandJob, KitHeartbeatResponse, FileUpload etc).

Starting with the June 2023 GDK, the file will be installed to %SDK\_ROOT%\toolKit\include\DevKitAgentAPI.yaml. The agent will interface with any service implementation that adheres to the OpenAPI contract.

For more information about the OpenAPI contract, see the following:

* [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/)
* [ASP.NET Core web API documentation with Swagger / OpenAPI](https://learn.microsoft.com/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-7.0)

## Agent Heartbeat Request

The following is an example of a heartbeat request following an executeCommandJob, formatted in JSON. The heartbeat contains details about the agent (schema version, uptime, etc), the console (ipAddress, runningApplication, etc), and job status of the agent (activeJobId, lastProcessedJobResult, etc). To see the full schema, you can load the DevKitAgentAPI.yaml into a variety of generators such as 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"
}
```

## Jobs

Jobs are single operations for the agent to process. There are currently four types of jobs:

* **executeCommandJob**: Executes a command on the console. The full set of <b>wd\*</b> commands are available to execute. You can find more information about wd\* console command line tools [here](/tools/tools-console/console_commandlinetools/consolecommandlinetools).
* **downloadFilesJob**:  The source URL of where to retrieve the file. This URL can be arbitrary and provides the same configured authentication as the heartbeat calls do. Calls are done via GET and aren't required to use SSL.
* **uploadFilesJob**:  The destination URL of where to upload the file. This URL can be arbitrary and provides the same configured authentication as the heartbeat calls. Calls are done via POST or PUT and aren't required to use SSL
* **cancelCurrentJob**: This job instructs the agent to cancel the currently running job.

<Note>> - Set WaitForExit to false on an Execute Command job to force a fire-and-forget execution. The LastProcessedJobResult property will not be populated with any output or exit code and the agent will immediately request the next job.</Note>

## Security and authentication

When using the agent, we designed a system that allows for secure and authenticated communication for the productions service and affordances during development.

The agent requires communication with the server over HTTPS and authenticates with the server using an Xtoken. As a result, the agent URI needs to be configured as a Relying Party in Partner Center.

* HTTPS lets the device know it's communicating with a trusted service, but HTTPS doesn't let the service know that the device is trusted.
* Xtokens are used so that the service can authenticate the device with the Developer Device ID (ddi) claim, to uniquely identify the development kit.

The agent passes a generated Xtoken to the server in the `XBOX-AGENT-XTOKEN` header of the heartbeat request. The server then decrypts and validates the tokens signature to authenticate the agent. The server can then respond with a new job or ignore the request.  A new claim has been added as an option for your Relying Party configuration called Developer Device ID (ddi). This new claim is designed to be used to ensure the device heartbeating to your service is expected. The ddi claim is available to any relying party configured in Partner Center but note that this claim will only be populated when running on XBOX Developer Kit, it will return null in retail. The ddi will return the XBOX Live Device ID for the device and the XBOX Live Device ID of your DevKit is available from xbdiaginfo or from Settings in the retail shell.

Above is the best practice for your production deployment and self signed certificates can be used with the DevKit agent and your service, fully chained certificates aren't required. In addition, during development when working with well known kits, inspecting the ddi on the server would not be required.

For more information about XTokens, see [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).

## Configure the DevKit Agent

Set two configuration values the console: the URI of the server (DevkitAgentServiceUri) and the Relying Party (DevKitAgentRelyingParty)

To set these values, go to a Microsoft Game Development Kit (GDK) command line, and then connect to the target console, issue the following commands.

```
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
```

### Starting and stopping the Agent

The Agent starts and stops automatically based on the presence of the DevKitAgentServiceUri configuration setting. To stop the agent, issue the following command from an XBOX Command Prompt

```
C:\Program Files (x86)\Microsoft GDK\bin>xbconfig DevKitAgentServiceUri=""
```

or send the equivalent wdConfig command via the agent server:

```
wdconfig DevKitAgentServiceUri=""
```

## See also

[Console Command Line Tools](/tools/tools-console/console_commandlinetools/consolecommandlinetools)


## Related topics

- [DevKit Agent process on XBOX consoles](/tools/tools-console/devkitagent/index.md)
- [Networking tools in the Microsoft Game Development Kit](/build/console-features/networking/tools/tools-networking-toc.md)
- [Setting up your XBOX Development Kit for streaming](/build/core-features/common/game-streaming/game-streaming-setup-xbox-developer-kit.md)
- [Tools](/build/console-features/networking/tools/index.md)
- [Managing console settings with XBOX Device Portal](/tools/tools-console/wdp/windows-device-portal-on-xbox-settings.md)