Use agents in the App Designer

Using an agent in the App Designer is similar to using an API, as you are fundamentally calling an endpoint of the Neptune DXP - Open Edition back end.

The App Designer provides the nep.ai.Agent resource to facilitate the usage of agents within apps. This component handles the communication with AI agents, including streaming responses and managing threads.

The nep.ai.Agent is a non-visual component. Pulling it into your app does not change anything visually. It is your task to call the agent’s methods at the appropriate place (for instance, on a button press event).

If you are looking for a pre-made visual component, take a look at the documentation for our pre-made AI components, such as the Chatbox, which utilizes nep.ai.Agent internally.

Configuration

After adding the nep.ai.Agent to your application resources, you can configure the following properties:

  • agent: The ID of the AI agent you want to use.

  • stream: Set to true to enable streaming of the response. If enabled, the onChunk event is fired as data arrives.

  • triggeredFrom: An optional string to identify the source of the request in logs (for example, MyApp).

Methods

The nep.ai.Agent provides several methods to interact with the agent and manage conversations.

generate(input, options)

This is the main method to send a prompt to the agent.

  • input (string): The text prompt to send to the agent.

  • options (object): Optional configuration for the request.

  • files (array): An array of file objects to upload with the request.

  • variables (object): Key-value pairs to inject into the agent’s context.

  • threadID (string): The ID of the thread to continue a conversation.

  • abortKey (string): A unique key to identify this request for abortion.

Thread management

  • createThread(title): Creates a new conversation thread.

  • listUserThreads(): Lists all threads for the current user and agent.

  • getConversation(id): Retrieves the message history for a specific thread.

  • renameThread(id, title): Renames a thread.

  • deleteThreadByIdAndUser(id): Deletes a thread.

Other methods

  • abort(key): Aborts a running request. If key is provided, it aborts the specific request; otherwise, it aborts all pending requests.

  • giveAgentFeedback({ id, feedbackPositive, feedbackComment }): Sends user feedback for a specific response ID.

  • getAgentMetadata(): Retrieves metadata about the configured agent.

Events

You can attach event handlers to process the agent’s activity.

  • onChunk: Fired when a chunk of text is received (only when stream is true).

    • Parameters: chunk (string), metadata (object).

  • onFinish: Fired when the generation is complete.

    • Parameters: metadata (object) containing usage stats, finish reason, and the full output.

  • onToolStart: Fired when the agent starts executing a tool.

  • onToolInput: Fired when the agent provides input to a tool.

  • onToolFinish: Fired when a tool execution completes.

Example usage

Here is an example of how to call the agent and handle the response in a script:

// Assuming the component is named 'oAgent'
var input = "Explain quantum computing in simple terms";

// Call the agent
oAgent.generate(input, {
    variables: {
        expertise: "beginner"
    }
}).then(function(response) {
    // Handle the final response (if not streaming)
    console.log("Finished:", response);
}).catch(function(error) {
    console.error("Error:", error);
});

If streaming is enabled, you would handle the onChunk event in the designer:

// Event handler for onChunk
var chunk = oEvent.getParameter("chunk");
var currentText = oTextOutput.getText();
oTextOutput.setText(currentText + chunk);

Related topics