Agent component in an app

The non-visual Agent component (nep.ai.Agent) gives you a direct, programmatic interface to an agent. Use it when you want to send a request yourself (for example, from a button press) and handle the response in your own app logic, rather than dropping in a ready-made chat UI.

  1. In the App Designer, open the Component library, go to nep.ai, and drag Agent into your app.

  2. Set the agent property to the ID of your agent.

A few properties worth knowing upfront:

  • stream: set to true to receive the response token by token via the onChunk event, instead of waiting for the full response.

  • triggeredFrom: an optional label (for example, MyApp) that appears in the Agent Trace, useful for filtering logs by source.

For all configuration properties, methods, and events see nep.ai.Agent component.

Send a single request

The simplest case: send a prompt and use the result. For example, from a button press, call generate() and display the response.

const result = await agent.generate("Your prompt here");

if (result.output) {
    responseText.setText(result.output);
}

Send a message within a thread

Use createThread() to start a conversation thread, then pass its ID to every generate() call to maintain context across messages.

const thread = await agent.createThread("Support session");

const result = await agent.generate(prompt, {
    threadID: thread.id,
});

if (result.output) {
    responseText.setText(result.output);
}

Handle streaming responses

If stream is enabled, the response is not returned by generate(). Instead, handle onChunk to append each fragment and onFinish to wrap up:

// onChunk
const chunk = oEvent.getParameter("chunk");
responseText.setText(responseText.getText() + chunk);
// onFinish
const metadata = oEvent.getParameter("metadata");
threadID = metadata.threadID;
busyIndicator.setVisible(false);

React to tool calls in the UI

When the agent calls a tool, you can react to it in two ways. Both give you access to the same event parameters.

Using the component events (declared in App Designer on the nep.ai.Agent resource, onToolStart and onToolFinish):

// onToolStart
const { toolName } = oEvent.getParameter("metadata");
statusText.setText(`Running: ${toolName}...`);
statusText.setVisible(true);
// onToolFinish
const { output } = oEvent.getParameter("metadata");
statusText.setVisible(false);
// output contains the tool's result, e.g. { message: "Email sent successfully" }
// note: onToolFinish does not include toolName — capture it on onToolStart by toolCallId if needed

Using attachEvent (programmatically, useful when wiring up logic at runtime):

agent.attachEvent("onToolStart", function (oEvent) {
    const { toolName } = oEvent.getParameter("metadata");
    statusText.setText(`Running: ${toolName}...`);
    statusText.setVisible(true);
});

agent.attachEvent("onToolFinish", function (oEvent) {
    statusText.setVisible(false);
});

For the full list of tool and streaming events see Agent events.

Related topics