Agent API for scripts

In the Script Editor, an agent dragged into a script is exposed as agents.<ContextName>(opts). Calling it sends a prompt to the agent and returns its response. Thread helpers live under p9.ai.

For how to add an agent to a script, see Agent in a script.

agents.<Name>(opts)

Sends a prompt to the agent. Without streaming, it returns a CompletionResponse object. With streaming, callbacks receive chunks as they arrive and it returns the full text string.

/*
 * AI Agent — agents.Test(opts)
 *
 * Non-streaming: returns a CompletionResponse object.
 * Streaming:     callbacks receive chunks as they arrive; returns the full text string.
 *
 * All options except `input` are optional.
 */

const result = await agents.Test({
    // Required: the prompt / question to send to the agent
    input: "Your prompt here",

    // Replace variables defined in the agent prompt
    // variables: { key: "value" },

    // Run as a specific user (defaults to the script's executing user)
    // user: { id: req.user.id },

    // Attach files (e.g. read from disk or passed in via request)
    // files: [{
    //     mimetype: "image/png",
    //     data: modules.fs.readFileSync("/path/to/file.png"),
    // }],

    // Enable reasoning mode (agent + underlying model must support it)
    // reasoning: true,

    // Continue an existing conversation thread
    // threadID: (await p9.ai.createThread(req.user.id, { title: "My conversation" })).id,
});

log.info("AI response:", result);

Options

input (string)

The prompt to send to the agent. Required; all other options are optional.

variables (object)

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

user (object)

Run as a specific user, for example { id: req.user.id }. Defaults to the script’s executing user.

files (array)

Files to attach, each { mimetype, data } where data is the file contents.

reasoning (boolean)

Enable reasoning mode. The agent and its underlying model must support it.

threadID (string)

Continue an existing conversation thread.

stream (boolean)

Stream the response. When true, provide the callbacks described under Streaming responses.

Streaming responses

You can also enable streaming for the agent response. This allows you to process the response as it is being generated, which is useful for long-running tasks or for providing immediate feedback.

To enable streaming, set stream: true in the options object and provide callback functions for the events you want to handle.

const result = await agents.Test({
    input: "Write a short story about a space adventure",
    stream: true,

    // Callback for each chunk of text received
    onChunk: (text) => { log.info("chunk:", text); },

    // Callbacks for tool execution lifecycle
    onToolStart: (part) => { log.info("tool started:", part); },
    onToolInput: (part) => { log.info("tool input ready:", part); },
    onToolFinish: (part) => { log.info("tool finished:", part); },

    // Callbacks for reasoning steps (requires reasoning mode)
    onReasonStart: (part) => { log.info("reasoning started:", part); },
    onReasonChunk: (text) => { log.info("reasoning chunk:", text); },
    onReasonFinish: (part) => { log.info("reasoning finished:", part); },

    // Callbacks for context compaction events
    onCompactStart: (part) => { log.info("compaction started:", part); },
    onCompactFinish: (part) => { log.info("compaction finished — success:", part.success, "logs:", part.logsCompacted); },

    // Callback when the generation is complete
    onFinish: (part) => { log.info("finished:", part); },
});

Thread management

Threads allow you to maintain conversation history across multiple agent calls. Use p9.ai.createThread to start a new thread and p9.ai.getThread to retrieve an existing one.

Create a thread

/*
    Creates a new AI thread for the given user.
    Returns the created thread object.
    Title is optional.
*/
const thread = await p9.ai.createThread(req.user.id);
// const thread = await p9.ai.createThread(req.user.id, { title: "My Thread" });
log.info("Thread created:", thread.id);

Pass the thread ID to an agent call to continue the conversation:

const result = await agents.Test({
    input: "What did we discuss earlier?",
    threadID: thread.id,
});

Get a thread

/*
    Gets an AI thread by ID.
    Returns null if the thread does not exist.
*/
const thread = await p9.ai.getThread(threadId);
if (!thread) {
    log.warn("Thread not found");
}

Related topics