nep.ai.Agent component

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 Chatbox, which uses nep.ai.Agent internally.

Configuration

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

agent (string)

The ID of the AI agent to use.

stream (boolean)

Set to true to stream the response. When enabled, the onChunk event fires as data arrives.

reasoning (boolean)

Set to true to enable reasoning/thinking mode. Effective only when the configured agent’s model supports reasoning.

triggeredFrom (string)

Optional label that identifies the request source in logs, for example MyApp.

Each property has standard UI5 accessors, for example getAgent() / setAgent(id) and getStream() / setStream(true).

Methods

The nep.ai.Agent exposes the following methods. Signatures use TypeScript notation; referenced types are described under Types.

generate(input, opts)

Sends a prompt to the agent and retrieves a response. When streaming is disabled the returned promise resolves with the full AgentResponse; when streaming is enabled it resolves with void and the response is delivered through events instead.

generate(input: string, opts?: AgentGenerateOptions): AbortablePromise<AgentResponse | void>
input (string)

The user’s input message or query.

opts (AgentGenerateOptions, optional)

Per-request options:

files ({ fileObject: File }[])

Files to include with the request, for example from a FileUploader control.

variables (Record<string, string>)

Values used to replace variables in the agent’s prompt.

threadID (string)

Thread to associate the request with, to continue a conversation.

abortKey (string)

Custom key for cancelling this request via abort(). Defaults to threadID (if provided) or a generated key.

Returns: an AbortablePromise resolving with the full AgentResponse (streaming disabled) or with void (streaming enabled). The promise also exposes an abortKey (string) property and an abort() method to cancel a mid-flight streaming request.

createThread(title)

Creates a new conversation thread.

createThread(title?: string): Promise<ThreadInfo>
title (string, optional)

A title for the thread.

Returns: a promise resolving with the new ThreadInfo.

listUserThreads()

Retrieves all threads created by the current user.

listUserThreads(): Promise<ThreadInfo[]>

Returns: a promise resolving with an array of ThreadInfo.

getConversation(threadId)

Retrieves the conversation history for a specific thread.

getConversation(threadId: string): Promise<AgentConversation[]>
threadId (string)

The thread whose history to retrieve.

Returns: a promise resolving with the thread’s ordered messages, tool calls, and reasoning steps.

renameThread(threadId, title)

Renames a thread owned by the current user.

renameThread(threadId: string, title: string): Promise<ThreadInfo>
threadId (string)

The thread to rename.

title (string)

The new title.

Returns: a promise resolving with the updated ThreadInfo.

pinThread(threadId)

Toggles the pinned state of a thread owned by the current user.

pinThread(threadId: string): Promise<ThreadInfo>
threadId (string)

The thread to pin or unpin.

Returns: a promise resolving with the updated ThreadInfo.

deleteThreadByIdAndUser(threadId)

Deletes a thread owned by the current user. If the deleted thread is currently active, it is cleared.

deleteThreadByIdAndUser(threadId: string): Promise<{ status: number }>
threadId (string)

The thread to delete.

Returns: a promise resolving with { status }, where status is 200 on success.

abort(key)

Aborts an in-progress streaming request.

abort(key?: string): void
key (string, optional)

The abortKey of a specific request to cancel. If omitted, all in-progress requests are aborted.

giveAgentFeedback(params)

Submits user feedback on a previous agent response.

giveAgentFeedback(params: AgentFeedbackParams): Promise<{ success: boolean; message: string }>
params (AgentFeedbackParams)
id (string)

The log ID of the response being rated.

feedbackPositive (boolean)

true for positive feedback, false for negative.

feedbackComment (string, optional)

A comment with more detail.

Returns: a promise resolving with { success, message } from the server.

getAgentMetadata()

Retrieves the agent’s metadata, including model configuration, equipped tools, MCP connections, reasoning flag, and output format.

getAgentMetadata(): Promise<AgentMetadata>

Returns: a promise resolving with the agent’s AgentMetadata.

Events

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

onChunk

Fired for each text fragment received (only when stream is true, and not during tool calls or reasoning steps).

Parameters

  • chunk (string): The text fragment.

  • metadata (object):

    • threadID (string): The ID of the current thread.

onFinish

Fired when the generation is complete.

Parameters

  • metadata (object):

    • createdAt (number): Timestamp of when the request was created.

    • finishReason (string): Reason for finishing (for example, "stop", "length").

    • input (string): User input for the request.

    • logId (string): Unique ID of the log entry.

    • model (string): Name of the model used.

    • modelResponseTime (number): Duration of the request in milliseconds.

    • output (string): Final output text from the agent. Mutually exclusive with structuredOutput.

    • structuredOutput (object): Structured JSON response, if the agent uses a structured output schema. Mutually exclusive with output.

    • reasoning (string): The agent’s reasoning text, if reasoning mode was active.

    • steps (Array<object>): Array of steps executed (for example, tool calls).

    • usage (object): Token usage details.

    • vectors (Array<object>): Sources used from vector search.

    • threadID (string): The ID of the current thread.

The following events are only fired when stream is true. When streaming is disabled, tool results and reasoning are available on the AgentResponse object returned by generate():

onToolStart

Fired when the agent starts executing a tool.

Parameters

  • metadata (object):

    • threadID (string): The ID of the current thread.

    • toolCallId (string): Unique ID of the tool call.

    • toolName (string): Name of the tool being called.

onToolInput

Fired when the tool’s input arguments are available.

Parameters

  • metadata (object):

    • threadID (string): The ID of the current thread.

    • toolCallId (string): Unique ID of the tool call.

    • toolName (string): Name of the tool being called.

    • input (any): The tool’s parsed input arguments.

onToolFinish

Fired when a tool execution is finished.

Parameters

  • metadata (object):

    • threadID (string): The ID of the current thread.

    • toolCallId (string): Unique ID of the tool call.

    • output (any): The tool’s result.

      Unlike onToolStart and onToolInput, this event does not include toolName. If you need the tool name, capture it on one of those earlier events and correlate by toolCallId.
onReasonStart

Fired when a reasoning step begins.

Parameters

  • metadata (object).

onReasonChunk

Fired for each reasoning text fragment.

Parameters

  • chunk (string): The reasoning text fragment.

  • metadata (object):

    • threadID (string): The ID of the current thread.

onReasonFinish

Fired when a reasoning step ends.

onCompactStart

Fired when conversation compaction begins (only when compaction is enabled on the agent).

Parameters

  • metadata (object):

    • threadID (string): The ID of the current thread.

onCompactFinish

Fired when compaction completes (success or failure).

Parameters

  • metadata (object):

    • threadID (string): The ID of the current thread.

    • success (boolean): Whether the compaction completed successfully.

    • logsCompacted (number): Number of conversation logs that were summarised. 0 if compaction was skipped or failed.

Subscribing to events with attachEvent

You can also subscribe to events directly on the nep.ai.Agent component using attachEvent:

Agent.attachEvent("onToolFinish", async function (oEvent) {
    const metadata = oEvent.getParameter("metadata");
    console.log(metadata);
});

The metadata object for onToolFinish looks like this:

{
  "threadID": "abc-123",
  "toolCallId": "0VQHt7kxu2UohiTB",
  "output": {
    "message": "Email sent successfully to terry@neptune-software.com"
  }
}

Types

The main shapes returned by the methods above.

AgentResponse

Resolved by generate() when streaming is disabled.

output (string)

Plain-text response. Present only when the agent is not configured with a structured output schema. Mutually exclusive with structuredOutput.

structuredOutput (Record<string, any>)

Structured JSON response. Present only when the agent is configured with a structured output schema. Mutually exclusive with output.

logId (string)

Unique identifier for the response log.

threadID (string)

Thread identifier, if the request was part of a thread.

finishReason (string)

Why generation stopped, for example stop or length.

model (string)

Provider model identifier used for the request.

provider (string)

The model provider.

modelResponseTime (number)

Duration of the request, in milliseconds.

createdAt (number)

Timestamp of when the response was created.

input (string)

The input that produced this response.

usage (object)

Token counts: promptTokens, completionTokens, cachedPromptTokens, reasoningTokens, totalTokens.

reasoning (string)

The agent’s reasoning text, if reasoning mode was active.

steps (AgentConversationStep[])

Ordered text, tool, and reasoning steps the agent produced.

vectors (object[])

Sources returned from vector search, if any.

error (string \| object \| null)

Error details, if the request failed.

ThreadInfo

id (string)

Unique identifier of the thread.

title (string)

Title of the thread.

createdAt (Date)

When the thread was created.

createdBy (string)

Identifier of the user who created the thread.

Related topics