Neptune DXP Documentation
Neptune DXP - Open Edition · 25.0 MTS

External agents

An external agent is an A2A agent hosted outside this instance, for example on another Neptune DXP - Open Edition instance or on a third-party platform. You register it in the Cockpit so that your own agents can use it as a peer.

An external agent has no model, instructions, or tools of its own on this instance. It cannot be run directly from the Playground or from an app. Attach it as a peer to another agent to use it.

Register an external agent

  1. In the Cockpit, go to the Agent tool and select Create.

  2. Set Type to External (A2A).

  3. Enter the Agent Card URL. This is the URL where the remote agent publishes its card, for example https://host/.well-known/agent-card.json. For an agent on another Neptune DXP - Open Edition instance, the card URL is https://[HOST]/api/AIBuildersKit/AIAgent/[AGENT-ID]/.well-known/agent.json.

  4. Optionally select an API Authentication to use when fetching the card and calling the agent. See Outbound authentication.

  5. Select Create.

The instance fetches the card and takes the agent’s name and description from it. Registering the same card URL again updates the existing entry instead of creating a second one. If the card URL points to a private or internal address, registration fails with Card URL not allowed.

Card Metadata tab

An external agent shows a Card Metadata tab instead of the model, instruction, and tool tabs.

Agent Card URL

The card URL entered at registration. You can change it here.

API Authentication

The proxy authentication used for calls to this agent. Empty means unauthenticated.

Reload Card

Fetches the card again with the current URL and authentication and stores the result.

Below the connection settings, the tab shows the stored card: Name, Description, Service Endpoint, Version, Protocol Version, Preferred Transport, Streaming, and Card Fetched. The stored card is refreshed automatically after one hour.

Outbound authentication

The API Authentication field references a Proxy Authentication artifact. The following types are supported for A2A calls:

Basic

Sends a fixed username and password.

OAuth 2.0 (Service-to-Service)

Fetches a service token with client credentials from any OAuth 2.0 token endpoint and caches it until it expires.

Neptune DXP Service Account (OAuth 2.0)

Fetches a service token from another Neptune DXP - Open Edition instance, using credentials created in that instance’s OAuth Clients tool. All calls act as the service user bound to the client.

Neptune DXP Open Edition User Token (JWT)

Mints a short-lived token for the user who is chatting with the calling agent, on every call. The remote instance sees the individual user, not a shared service account. See Propagate users between instances.

Client certificate types and proxy authentications that use the Cloud Connector are not supported for A2A calls.

Propagate users between instances

With the JWT type, each user of the calling instance is identified individually on the remote instance. The remote instance creates the user on first contact and assigns the configured roles.

On the calling instance:

  1. Create a proxy authentication of type Neptune DXP Open Edition User Token (JWT).

  2. Set Token Signing to Instance key / JWKS (ES256). The token is then signed with the instance’s own key, and the remote instance verifies it against https://[CALLING-HOST]/.well-known/jwks.json. With Shared secret (HS256) both instances must hold the same secret instead.

  3. Enter an Issuer and, if you want, an Audience. The remote instance checks both.

  4. Select this proxy authentication as API Authentication on the external agent.

On the remote instance:

  1. Go to the System Settings to → Authentication and add a JWT Validation login method. See Configure JSON web token (JWT) API authentication.

  2. Set Jwks Url to https://[CALLING-HOST]/.well-known/jwks.json, or enter the shared secret.

  3. Enter the same Issuer and Audience as on the calling side.

  4. Map the username claim to Username, and configure the roles and groups new users should receive.

  5. Assign the agent’s role to those users through the role assignment, so that the propagated users are allowed to call the agent.

The minted token is valid for 60 seconds by default. Raise Token Lifetime (seconds) if the clocks of the two instances differ.

Related topics