Overview

AI Colleagues are autonomous digital personas that can execute complex tasks on behalf of employees. Each AI Colleague is powered by Agent Operating Protocols (AOPs) — the natural language instructions that define how it works — and Skills — the technical capabilities (APIs, Workflows, MCP integrations) that define what it can do.

End-users don't need to understand this underlying architecture. They simply chat with the Virtual Assistant, and the system automatically identifies the right AOP or Skill to fulfil their request.

This guide explains how end-users can discover and invoke AOPs and Skills through the Virtual Assistant, and how the system orchestrates that process behind the scenes.

---

How It Works

When an end-user sends a message to the Virtual Assistant, the AI Colleague's Orchestrator processes the query through a multi-step pipeline to determine whether an AOP or Skill should be invoked.

1. Discovering What's Available

End-users can ask the Virtual Assistant what it can do using natural language phrases such as "What can you do?", "Show me options", "How can you help me?", or "Help me get started."

When the assistant detects this intent, it invokes the Capability Discovery Flow — a built-in system tool that retrieves a personalised menu of available capabilities. This menu is curated from the bot's Capabilities Catalog, which links user-friendly labels to underlying AOPs and Skills. Learn more about enabling capability discovery flow here.

The discovery menu is personalised for each user. The system retrieves the user's audience memberships (based on department, location, or custom segments) and filters the available capabilities accordingly. A user in the Finance department, for example, will not see HR-only processes. Within the visible set, pinned capabilities appear first (up to 7 items), followed by a rotating selection of other available options. All labels and greetings are automatically localised into the user's preferred language.

2. Triggering an AOP

AOPs are multi-step, instruction-driven procedures — think of them as run-books that the AI Colleague follows autonomously. An end-user triggers an AOP simply by describing their need in the chat.

Example:

User: "I need to onboard a new hire starting next Monday."

Assistant: "I can help with that! Let me gather the required details..."

Behind the scenes, the Orchestrator matches the user's query to the most relevant AOP using semantic reranking — a process that scores all available AOPs against the user's message and selects the best match. Once matched, the system creates an execution thread dedicated to that AOP, and the AI Colleague begins following the AOP's step-by-step instructions.

During execution, the AOP may invoke Skills (such as calling an HRMS API to create the employee record), ask the user for additional information, or hand off to a sub-procedure (Helper AOP) for a specific part of the task.

AOPs can only be triggered via chat if the administrator has enabled manual execution for that process (is_manual_execution_allowed = true). Some AOPs are restricted to scheduled execution only (via the Workbench) and will not appear in user-facing interactions.

3. Triggering a Skill Directly

Not every user request requires a full AOP. For simpler, single-action tasks, the Orchestrator may invoke a Skill directly — without an AOP wrapper.

Example:

User: "What's the leave balance for employee ID 4521?"

Assistant: (invokes the get_leave_balance API skill and returns the result)

The Orchestrator assembles a dynamic toolset for each request by aggregating Skills from several sources: dashboard-configured API skills, Workflow-based skills, MCP tool integrations, and AOP-backed procedures.

Skills are also subject to audience filtering — a skill is accessible to a user only if it has no audience restrictions (global access) or if the user belongs to at least one of the skill's configured audience groups.

4. Conversational Data Collection

When an AOP or Skill requires input that the user hasn't provided, the Virtual Assistant enters an interactive collection mode. Rather than failing, the assistant asks the user for the missing information conversationally.

Example:

Assistant: "To submit your leave request, I'll need a few details. What type of leave is this — casual, sick, or earned?"

User: "Casual leave."

Assistant: "Got it. And what dates would you like off?"

Once all required parameters are collected, the system proceeds with the execution — calling the relevant API, triggering the workflow, or completing the AOP steps.

5. Asynchronous & Long-Running Tasks

Some Skills involve workflows or external systems that don't return results immediately. In these cases, the system supports asynchronous resumption:

• The Virtual Assistant informs the user that the task is in progress.
• The execution thread is paused and awaits a callback from the external system.
• Once the callback arrives, the assistant resumes the conversation and delivers the result or next steps to the user.

This ensures that long-running processes (like multi-level approvals or external system integrations) don't block the conversation or require the user to wait.

---

What End-Users See

From the end-user's perspective, interacting with AOPs and Skills is seamless. Here's a summary of what a typical interaction looks like:

---

Key Concepts for End-Users

Capabilities Menu — The personalised list of actions the assistant can perform for you. Ask "What can you do?" to see it. The menu adapts based on your role, department, and location.

AOPs — Complex, multi-step tasks the assistant can handle end-to-end, like submitting a leave request, initiating an onboarding, or running a compliance check.

Skills — Specific single actions the assistant can perform, like looking up your leave balance, fetching a document, or creating a ticket in an external system.

Audience-Based Access — Not all capabilities (AOPs/Skills) are visible to every user. The system ensures you only see and can trigger actions that are relevant and authorised for your role.

---

How Admins Enable This Experience

For the end-user experience described above to work, administrators configure the system through the AI Colleague Studio in the admin dashboard. The setup involves three layers:

Identity — Creating the AI Colleague

Admins create an AI Colleague by defining its persona: a name, job title, job description, and an escalation contact (a human fallback). This is done in AI Colleagues > AIC Management. The persona guides the assistant's tone and behavior during conversations.

Logic — Authoring AOPs

Admins write Agent Operating Protocols using the AOP Creator, which supports AI-assisted generation, Markdown-based instructions, and LLM-powered validation. Each AOP defines the step-by-step logic the AI Colleague follows, the Skills it can use (referenced via @skill_name mentions in the instructions), and the audience restrictions that control who can trigger it.

AOPs are classified as either Primary (standalone entry points that users can trigger) or Helper (sub-routines invoked by other AOPs). Admins also configure execution permissions — whether an AOP can be triggered manually via chat, via scheduled runs on the Workbench, or both.

Capability — Registering Skills

Skills are registered in the Skills Registry under AI Colleagues > Skills. Each skill has a unique identifier, a description (used by the AI for intent matching), audience restrictions, and an execution scope that determines whether the skill is available to the main Orchestrator, within AOP execution, or both.

Skills support several types: REST API integrations (GET/POST with JSON schema definitions), Workflow-based skills (linked to internal workflow apps), MCP integrations (tools from external servers via Model Context Protocol), and Employee Directory lookups.

Discovery — Curating the Capabilities Menu

Admins manage the Capabilities Catalog to control what appears in the "What can you do?" menu. They can generate user-friendly labels from technical tool descriptions using AI, pin up to 7 high-priority items, and preview the end-user experience. The catalog automatically reflects the active/inactive status of the underlying Skills and AOPs.