# Spark Agent2Agent integration

{% hint style="warning" %}
This documentation references external sources. Nexthink does not have control over the accuracy of third-party documentation, nor any external updates or changes that might create inconsistencies with the information presented on this page. Please report any errors or inconsistencies to [Nexthink Support](https://support.nexthink.com/).
{% endhint %}

Integrate Spark with your existing enterprise AI bots using the [Agent-to-Agent (A2A)](https://a2a-protocol.org/latest/) protocol, allowing employees to continue working in the tools and conversational interfaces they already use and trust.

The A2A protocol is an open standard that enables seamless communication and collaboration between AI agents. Through A2A, third-party agents can discover, invoke, and track Spark capabilities, including querying rich device and user insights, executing safe and guardrailed actions, receiving asynchronous callbacks, and presenting clear, human-readable outcomes.

As a result, employees experience no disruption to existing workflows while seamlessly extending them with Spark’s intelligence and Nexthink context.

This page provides a step-by-step guide to setting up agent-to-agent communication via the public vendor-neutral API.

{% hint style="info" %}
If your organization is not using AI agents that support the A2A protocol, but you still want employees to access Spark through existing chat entry points, you can implement a lightweight chatbot integration directly with the Spark API.

Refer to [Spark Handoff API](https://docs.nexthink.com/api/spark/handoff-api), for more information.
{% endhint %}

## Key benefits

* Integrate external AI agents with **Spark API** using a standardized protocol
* Extend existing chatbot or orchestration workflows with Nexthink capabilities
* Enable multi-turn conversations using context-aware interactions
* Maintain user context across conversations using metadata and task tracking
* Ensure enterprise security with authenticated, service-to-service communication

## Understanding Spark A2A workflow

<figure><img src="/files/lW0PKkWfux7V2Vm1FUtH" alt=""><figcaption></figcaption></figure>

Once integrated, the workflow is as follows:

1. The employee reports an issue, requests a service, or asks a question using their existing chatbot (primary AI agent).
2. Spark exposes its Agent Card to that primary AI agent.
3. The primary AI agent reads the Agent Card and identifies Spark as the appropriate subagent.
4. The primary AI agent sends the employee request to Spark, including the `contextId` and `taskId` values (for multi-turn conversations, these must be reused from previous responses).
5. Spark processes the request using its advanced capabilities and domain-specific intelligence, and sends the response asynchronously to the configured webhook.
6. The primary AI agent receives the response and returns it to the employee.
7. The cycle repeats, reusing the same `contextId` and `taskId` to maintain the conversation context.

***

## Configuring Agent2Agent integration

### Prerequisites

Ensure the following prerequisites are met to integrate your existing AI bot with Spark usin A2A protocol:

* Spark is configured and integrated in your environment. For more information, see the [Setting up and managing Spark](/platform/user-guide/spark/setting-up-and-managing-spark.md) documentation.
* You need to have the **Administrator** role in Nexthink Infinity. For more information, see the [Roles](/platform/user-guide/administration/account-management/roles.md) documentation.

Follow these steps to complete the agents' integration.

{% stepper %}
{% step %}
**Configure Spark API credentials**

To allow sending authenticated requests from other agents, first configure Spark API credentials in the Nexthink web interface:

* From the **Administration > API Credential,** select the **New OAuth client credentials** button.
* Provide a name and optional description and select the **Spark API** permission.
* After saving your credentials, a new modal appears with the OAuth client credentials. For security reasons, the credentials appear only once. Copy and save them securely, as you cannot access them beyond this point.
  {% endstep %}

{% step %}
**Configure connector credentials for HTTPS**

To enable Spark to send asynchronous push notifications, configure **Connector credentials** that point to your webhook endpoint.

* From the **Administration > Connector credentials,** select the **New credentials** button.
* Provide a unique credentials name and select **Hypertext Transfer Protocol Secure (HTTPS)** from the **Protoco**l drop-down menu.
* Provide the exact **URL address** exposed by your external agent in the message payload. Make sure it follows the `https://{host}:{port}/` format.
  * The same URL you provide in the `pushNotification.url` field when sending requests.
* Select the used authorization.
  {% endstep %}

{% step %}
**Enable external agent integration using the A2A client SDK**

Configure your external agent using the A2A client SDK to communicate with the Spark A2A API.

* Configure the SDK with the base URL:\
  `https://[instance].api.[continent].nexthink.cloud/api/spark/a2a`
* Authenticate all requests using the OAuth client credentials configured in Step 1.
* Send messages through the SDK using the `message:send` endpoint.
* Include the user identity in each request by setting the `userPrincipalName` (email address) in the `metadata` field of the payload.
* Ensure each request contains:
  * A unique `messageId` (generated by the client)
  * `contextId` and `taskId` for multi-turn conversations (the client must reuse the values returned by Spark; if they are not provided in subsequent requests, Spark generates new ones, starting a new context)
* Configure a webhook URL to receive asynchronous push notifications from Spark.

{% hint style="info" %}
Push notification callbacks are not authenticated.
{% endhint %}

* Store and reuse the `contextId` and `taskId` returned in the first response to maintain conversation continuity.
* Evaluate the task object in responses to determine the conversation status.
  {% endstep %}
  {% endstepper %}

{% hint style="info" %}
Only the `agent card` and `message:send` APIs are currently supported.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nexthink.com/platform/configuring_nexthink/bringing-data-into-your-nexthink-instance/integrating-nexthink-with-third-party-tools/spark-agent2agent-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.