If you already use Nexthink Infinity, try Workspace, powered by Nexthink Assist, for AI-powered answers and troubleshooting.
Ctrlk
Support
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Spark Agent2Agent integration

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.

Integrate Spark with your existing enterprise AI bots using the Agent-to-Agent (A2A) 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.

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, for more information.

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

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 documentation.

  • You need to have the Administrator role in Nexthink Infinity. For more information, see the Roles documentation.

Follow these steps to complete the agents' integration.

1

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.

2

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 Protocol 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.

3

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.

Push notification callbacks are not authenticated.

  • 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.

Only the agent card and message:send APIs are currently supported.

Last updated

Was this helpful?