> For the complete documentation index, see [llms.txt](https://docs-conversational-ai.syntphony.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-conversational-ai.syntphony.com/studio/ai-agents/supervisor.md).

# Supervisor

## Overview

The Supervisor is the orchestration component of the Project. Its role is to control how user requests are processed according to the selected [**governance type.**](https://docs-conversational-ai.syntphony.com/project/governance-types.md)

It is a guided AI system that operates within a predefined decision architecture established during system design.

The system does not act independently of its configuration. Instead, it follows structured decision paths, applies configured intent logic, and uses only the capabilities and constraints defined in its system prompt and orchestration layer. \
\
Its behavior is therefore governed, predictable, and aligned with the interaction model defined at design time, using **native capabilities defined in the system prompt, as described below:**

#### What the Supervisor does

* **Reviews** each user interaction to understand what is being requested
* **Uses** structured decision logic to determine the most appropriate next step
* **Routes** requests to the most appropriate Agent or Flow based on the project’s governance type
* **Applies** fallback responses when a request cannot be assigned to a specific agent
* **Responds** to chit-chat, including questions about the company or its own Persona
* **Clarifies** ambiguous requests when necessary to ensure proper routing
* **Passes** relevant conversation context to AI Agents to ensure continuity.

## How to Configure the Supervisor

The Supervisor is automatically created when a Project is initialized.

It is a **system-level component**, and its core orchestration behavior is governed by the platform. This behavior cannot be overridden by user configuration.

Configuration is performed through the Agents page. Available fields allow refinement of behavior, but do not alter governance rules or decision logic.

<figure><img src="https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2FIkKBumlvawjnpc1CzjCI%2Fimage.png?alt=media&amp;token=40d1e13e-b79f-41cf-8fc8-dfbccb14ad78" alt=""><figcaption><p>Agents page - Supervisor drawer modal</p></figcaption></figure>

All configurations must respect the Supervisor’s role:

* It **does not execute tasks**
* It **does not guess or make decisions independently**
* It **follows predefined rules**
* It **operates strictly as a governance-controlled orchestration layer.**

### Role

The Role defines the Supervisor as the orchestrator of agents and flows within the Project, only if the project is configured by Agentics or Composite Agentics First. <br>

<figure><img src="https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2FCSc61jgGpYKJGwtilY4V%2Fimage.png?alt=media&amp;token=1b4b1ed4-7067-4c2d-8f50-6b67076f4b6a" alt=""><figcaption><p>Supervisor role. This field cannot be edited.</p></figcaption></figure>

### Goal

The Goal is predefined and cannot be edited:

> Responsible for processing user inputs, analyzing requests, and delegating them to the appropriate specialist agent.

<figure><img src="https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2Fq7JSK5IyuGjLYDXVicaD%2Fimage.png?alt=media&amp;token=328a1ddc-796a-4389-bc2c-b40ad9bf0b3b" alt=""><figcaption><p>Supervisor Goal field </p></figcaption></figure>

This definition reflects the **Supervisor’s fixed responsibility within the system.**

#### Clarifications about the Goal´s field definition

* **“Processing user inputs”** refers to analyzing and understanding the user input, structuring the request context, and routing it to the most appropriate agent based on the best topic match, not generating final outputs
* **“Analyzing requests”** means the Supervisor does not select agents based on subjective reasoning. All routing follows structured rules defined by user input and governance. It operates as a decision layer, not as an executor
* **"Delegating”** is performed through governance-driven routing, not dynamic or improvised decisions
* The Supervisor **passes structured context to agents**, enabling them to act with full understanding of the user request
* The Supervisor does **not generate final task outputs**, except in controlled scenarios such as fallback or chit-chat.

{% hint style="info" %}
The immutability of this field ensures consistency, alignment with system logic, and prevents misuse. The **Role** and **Goal** fields of the Supervisor are immutable to preserve the logic of the agentic layer provided by the SCAI product.
{% endhint %}

### Persona

The Persona defines the communication style applied to the Supervisor and all Agents within the Project. It establishes the overall personality, including tone of voice, communication style, and background.&#x20;

A persona can be modified at any time, regardless of whether the agent uses a single persona or multiple personas.

The Persona affects **how the system communicates**, not how it operates.

<figure><img src="https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2FEGdcpqhXwSK01Ib9QjhA%2Fimage.png?alt=media&amp;token=d6910d8b-03ba-4edc-842c-2f7806504332" alt=""><figcaption><p>Supervisor Persona step and respective fields</p></figcaption></figure>

### Instructions

The Instructions field defines high-level behavioral guidance for the Supervisor.

Instructions act as a complementary layer that enhances the Supervisor’s behavior, as long as they remain aligned with its native orchestration logic. They can reinforce rules such as topic disambiguation or refine how agent derivation should occur.

<figure><img src="https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2FATiDYNkgQEon30w574HC%2Fimage.png?alt=media&amp;token=5f0c778e-bc26-410f-bdd9-3ecd02cb2a4a" alt=""><figcaption><p>Supervisor Instruction field. Instructions <em>refine behavior, not logic.</em></p></figcaption></figure>

#### ✅ What they do

* **Act as a complement**, guiding how the Supervisor should manage specific scenarios (for example: by defining greeting criteria)
* **Extend the handoff capability to Agents or NLU flows**. For example: they may indicate that a Specialist Agent should immediately trigger a specific action or clarify how an Agent should be activated for a given use case
* **Reinforce** the Supervisor’s ability to perform disambiguation before routing to the appropriate Agent
  * Although the Supervisor has this native capability, **additional Instructions may be required in some cases to make disambiguation more effective**
* The Supervisor **may also suggest an execution order for triggering Agents or NLU flows.** For example, trigger the Authentication Agent before the Orders Agent.

#### ❌ What they do not do&#x20;

* Conflict with the Supervisor’s native capability to route to Specialist Agents or NLU flows, as defined in the Goal field
* Enforce rigid routing. The Supervisor already uses the Role and Goal fields of Specialist Agents to determine the most appropriate routing. There is no need to instruct how them should be triggered unless a business rule requires coordinating their execution
* Override governance, system prompt, or any project configuration
* Conflict with other fields that influence the Supervisor, such as Persona or other configuration fields.

{% hint style="info" %}
Always follow native recommendations strictly. Any attempt beyond default configurations may result in unintended behavior, such as tool hallucinations.
{% endhint %}

### Rules

The Rules field defines explicit decision rules that determine how the Supervisor routes and prioritizes requests.

They are **objective, scenario-based conditions** that directly impact routing behavior.

**Rules** serve the same purpose as **Instructions**, but they allow topic segmentation. The way **Rules** fields are filled out follows a different concept. **Example on how to fill in this field:** when sending a greeting message, the **Supervisor** must always use the user's name.

### Fallback management

Any interaction that cannot be handled within the Project’s defined capabilities is managed through a **controlled fallback mechanism**.&#x20;

The Supervisor triggers fallback when no governance rule, eligible agent, or applicable flow can resolve the request.

Fallback is not an alternative reasoning path. It is a **strict boundary condition** that ensures the system does not operate beyond its defined scope.

{% hint style="info" %}
Fallback is **controlled and non-generative**. The Supervisor only responds with what is explicitly defined within the Project.
{% endhint %}

<figure><img src="https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2F7fZu3TE0m3TEjgsizYFt%2Fimage.png?alt=media&amp;token=393f054f-8579-4399-a571-c3df0e8d2202" alt=""><figcaption><p>Fallback management field on Supervisor's agent general information</p></figcaption></figure>

Fallback operating constraints:

* The Supervisor does not hallucinate or improvise responses
* It only responds based on information available in the Project
* No unsupported or external information is introduced.

### Guardrails

#### What they are

Guardrails act as an additional layer of protection within the system, reinforcing behavioral boundaries and reducing operational or security risks during interactions.

Their function is to complement the base orchestration structure without replacing or altering the rules defined in the Supervisor.

{% hint style="info" %}
Guardrails help ensure that agent and flow behavior remains aligned with Project guidelines.
{% endhint %}

<figure><img src="https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2Feccz8Ikp673iMqF0tanb%2Fimage.png?alt=media&amp;token=07e91e08-4fa8-494e-ad8a-28ca69de5bb0" alt=""><figcaption><p>Guardrails field on Supervisor general information</p></figcaption></figure>

They **enable:**

* Reinforcement of behavioral and compliance restrictions
* Prevention of responses that fall outside defined policies
* Maintenance of consistency with the system’s operational rules.

#### Guardrails inheritance behavior

Guardrails can be inherited from the Supervisor to Specialist Agents.

They are designed to propagate **rules and boundaries** in a structured and consistent way across the system.

There are **two types of Guardrails inheritance**:

* **As-is inheritance**: the Specialist Agent inherits the Supervisor’s Guardrails and remains **automatically synchronized** with any updates made to the Supervisor’s Guardrails field
* **Customized inheritance**: the Specialist Agent inherits the Supervisor’s Guardrails but can **edit and extend them**. In this case, **no further synchronization occurs.**

### Advanced settings <a href="#advanced-settings" id="advanced-settings"></a>

When using compatible models, you can fine-tune how the model generates responses through model-specific settings, including **Temperature, Top P, Reasoning Effort, Verbosity**, and more. Available options vary by provider and model.

Learn more about [**Advanced Model Settings**](https://docs-conversational-ai.syntphony.com/language-models/advanced-model-settings.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs-conversational-ai.syntphony.com/studio/ai-agents/supervisor.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
