How the Assistant works

The PeopleSoft Assistant is a small service between a chat page in PeopleSoft and an LLM. The LLM decides what information it needs; the service fetches it from PeopleSoft APIs, as the signed-in user; and the answer comes back to the chat page as it’s written.

The Assistant service holds no PeopleSoft password. It calls PeopleSoft with a token for the signed-in user, so PeopleSoft's own security decides what each answer can include.

The parts

• The chat page is a Fluid component, such as ZZ_AI_ASSISTANT, whose page holds an HTML area for the chat. Its PostBuild PeopleCode loads the chat’s JavaScript and style sheet with the AddJavaScript and AddStyleSheet functions. Users open it from a tile on their homepage or the NavBar, or from a Magic Button, which also tells it the page and field they were on.
• The Assistant service is a web service you run close to PeopleSoft. It holds the LLM credentials, the tool catalog, and the system prompt. It runs the tool loop, streams answers, and writes the audit log. It has no PeopleSoft password and no database connection.
• The LLM plans each answer. It sees the system prompt, the tool definitions, the conversation, and the results of the tools it asked for. It never reaches PeopleSoft itself; it asks the service to call a tool, and the service decides whether to.
• The identity provider is the one your organization already uses for sign-in. It signs the user in to the Assistant, and exchanges their token for one that PeopleSoft accepts; see Acting as the user.
• PeopleSoft application services are REST APIs built with the Application Services Framework (ASF), available since PeopleTools 8.59. Each tool calls one API operation. PeopleSoft checks the user’s permission lists before it runs, and the API applies row-level security.

One turn, step by step

Here’s what happens when a user asks “How many vacation hours do I have left?”:

1. The chat page sends the question to the Assistant service, with the user’s access token and any page context from a Magic Button.

2. The service checks the token and loads the conversation so far.

3. The service asks the LLM, sending the system prompt, the tool definitions, the conversation, and the new question.

4. The LLM asks for a tool: get_absence_balances, with no arguments, because the question is about the user’s own balances.

5. The service runs the tool. It checks the arguments against the tool’s input schema, calls the application service with a PeopleSoft token for the user, and gets JSON back. PeopleSoft returns only this user’s balances, because the token identifies them.

6. The service sends the result to the LLM, which can ask for more tools. The loop repeats until the LLM has what it needs.

7. The LLM writes the answer, and the service streams it to the chat page as it’s written, with a link to the page where the user can see the details.

8. The service writes an audit entry for the turn: who asked, which tools ran, and how long each took.

As the service sees it, the turn looks like this:

One turn, from the service's point of view

user       How many vacation hours do I have left?
tool call  get_absence_balances {}
result     {"balances": [{"plan": "Vacation", "hours": 46.5,
            "asOf": "2026-09-24"}]}
answer     You have 46.5 hours of vacation as of today.
           [View your absence balances]

The tool loop

The LLM decides which tools to call; the service decides whether and how to run them:

• Only catalog tools run. A call to a tool that isn’t in the catalog, or with arguments that don’t match its schema, is refused without reaching PeopleSoft.
• Independent calls run together. When the LLM asks for several tools at once, such as balances for two absence plans, the service runs them in parallel and returns all the results together.
• Errors go back to the LLM. When PeopleSoft refuses a call, for example because the user’s permission lists don’t include the API, the service returns the error as the tool’s result. The LLM can then explain what happened, instead of guessing.
• Loops are bounded. A turn can make at most 8 tool calls, and each call times out after 20 seconds. When a limit is reached, the LLM is told to answer with what it has.

Streaming

Answers are streamed to the chat page with server-sent events, so the user reads the answer as the LLM writes it, instead of waiting for all of it. While a tool runs, the chat page shows what the Assistant is doing, such as “Checking your absence balances”, from the tool’s progress message in the catalog.

If a proxy such as nginx sits in front of the service, turn off response buffering for the chat endpoint, or the whole answer will arrive at once.

What each part keeps

Part	What it keeps
The chat page	The visible conversation, in the browser, until the user closes the page or signs out of PeopleSoft
The Assistant service	The conversation, including tool results, for up to 8 hours, so that follow-up questions work; and the audit log
The LLM provider	Whatever its terms allow; check that your agreement with the provider covers the data your APIs return
PeopleSoft	Nothing new; the APIs read data and change nothing

The service keeps no copy of PeopleSoft data beyond the conversation it belongs to, and deletes each conversation when it expires.