How to build a chatbot in Workday Extend

Which kind of chatbot to build in Workday

If the chatbot has to answer from Workday data or act in Workday, build a Custom Agent. Users reach it in Workday's Self-Service Agent chat panel and in Sana, and what it can do is set by a security group in Agent System of Record (ASOR). If you need a chat screen inside your own Extend app, for example a help assistant on an Equipment Request page, build it yourself: a page that keeps the conversation and a synchronous orchestration that sends it to a model API.

A third option is often mistaken for a chatbot. The aiPrompt attribute on a richText widget on an edit page generates text from a configured prompt when the user clicks a button. It has no conversation and no follow-up turn, and Workday caps it at 2 buttons per aiPrompt, 3 aiPrompt widgets per app and 1,000 characters per prompt including the values you insert. It is the right tool for "draft a job description from these fields", not for chat. AI widgets are an Extend AI feature.

Route 1: a Custom Agent in the Workday chat panel

A Custom Agent is two files in the agentskills.io format: an .agent definition and one or more .agentskill files listing the tools the agent may use, by name and WID. You build them in App Builder, by hand or with Developer Agent, in either an Extend app or an Agent app. Agent apps hold only agents, skills, attributes and orchestrations, cannot contain PMD or model components, and do not count against your Extend app entitlement.

The mechanism that matters for a chatbot is what happens after deploy. ASOR registers the agent automatically in a development environment, but the agent stays hidden from users until you assign a security group and activate it in ASOR. On first activation Workday creates an Agent System User (ASU) named after the agent, and every tool call runs under the ASU's token. User security and agent security are separate: a user can ask the agent to do something they cannot do themselves, and the reverse. Design the ASU's security group as carefully as an integration system user's.

The agent runtime cannot make arbitrary API calls, even to Workday. Every call goes through one of its dedicated clients: Workday's agent-ready tools through the Agent Gateway, and your own logic through Custom Agent Action orchestrations. So anything the chatbot needs that no delivered tool provides becomes a Custom Agent Action orchestration. For moving to higher environments, Workday requires configuring the agent in Workday App Manager and completing ASOR registration and security there. The step-by-step build is in building your first Workday custom agent, and the security model in securing Workday custom agents.

Route 2: a chat page inside an Extend app

Workday does not ship a chat widget for Extend pages, so the in-app chatbot is a pattern you assemble from documented parts.

Keep the conversation on the page

Store the turns in pageVariables as a list of role and text pairs, render them in a dynamicSection, and add a text input and a pageActionButton. The button's onClick appends the user's turn, calls a deferred endpoint, appends the reply and refreshes the section. A deferred endpoint is not called on page load; the page calls it from script with invoke(), which returns the response object.

{
  "name": "askAssistant",
  "baseUrlType": "workday-orchestrate",
  "url": "<% site.applicationId + '/orchestrations/AskAssistant/launch' %>",
  "httpMethod": "POST",
  "authType": "sso",
  "deferred": true,
  "onSend": "<% return {'messages': pageVariables.history}; %>"
}

{
  "type": "pageActionButton",
  "id": "sendButton",
  "label": "Send",
  "onClick": "<%
    pageVariables.history.add({'role': 'user', 'content': question.value});
    var result = askAssistant.invoke();
    pageVariables.history.add({'role': 'assistant', 'content': result.reply});
    conversation.data = pageVariables.history;
    question.value = '';
  %>"
}

Initialise pageVariables.history to an empty list in the page's onLoad. The endpoint shape, base URL type workday-orchestrate with the path <applicationId>/orchestrations/<Name>/launch, is the one Workday's App Catalog sample apps use to launch an orchestration from a page; the Document Intelligence with the AI Gateway sample is a compact example to compare against.

Call the model from a synchronous orchestration

Create the orchestration from the Synchronous template. Inside it:

1. Read messages from the launch request.
2. Build the model provider's request body in a Create Text Template step set to application/json, adding your system instructions as the first message.
3. Send it with a Send HTTP Request step. This component is for external URLs; Workday says not to use it for Workday APIs, which go through Send Workday API Request instead.
4. Read the reply text out of the response with a JSONPath accessor and return it as reply from the end step.

Put the provider's key in an orchestration credential, not in the page or the template. On the orchestration's Settings, Credentials tab, an API Key credential takes a key and value pair and lets you choose whether Workday appends it to the header or the query parameters. Select that credential on the Send HTTP Request step's Auth tab.

If the bot should answer from Workday data, fetch that data in the same orchestration with Send Workday API Request before you build the prompt, and send the model only the fields the answer needs. Do not let the model choose which Workday endpoint to call from the user's text: in this pattern the orchestration decides what is read, and Workday security applies to the credential that reads it.

Mind the 25-second limit

A synchronous orchestration triggered by a presentation page has 25 seconds in total, and that limit overrides any timeout you set on the steps. A long model answer plus a Workday read can exceed it. Keep the reply short in your system instructions, set the Send HTTP Request's response timeout below the page budget so the flow can return a readable error, and trim old turns from messages before sending, because the whole history travels with every turn.

Why not a connector

Orchestrate's AI connectors include chat actions for services such as OpenAI (ChatGPT) and Anthropic (Claude), and they save you the HTTP work. They are available only to Extend AI customers and only in orchestrations created from the Custom Agent Action template, so a page-launched synchronous orchestration cannot use them. A connector also runs as the account connected to it, not as the user, and Workday states that connector data is processed by Pipedream in the AWS us-east-1 region regardless of where the tenant is. Read the Connector Security and Data Processing page with whoever owns data residency before you use one in a Custom Agent.

Prove the chatbot works

For a Custom Agent, sign in as a user in the group you secured it to and confirm the agent appears in the chat panel; sign in as a user outside it and confirm it does not. Ask a question that needs a tool, then check the result in Workday and in the agent's traces in App Hub, rather than trusting the reply text.

For the in-app chatbot, run a three-turn conversation in which the third question only makes sense with the first, which proves the history is reaching the model. Then open the orchestration's run and check the Send HTTP Request step's status and the logged request: confirm the system instructions are there and the key is not in the logged body. Repeat with a long question to see what the user gets when the 25-second budget runs out. Credential and request-body failures are covered in the Orchestrate error guide.