# AI Agents AI Agents are the core building blocks of an intelligent conversational experience. AI Agent is a finely-tuned entity designed to excel in a specific domain, equipped with unique knowledge bases, predefined Action capabilities, tailored communication style, and security protocols. These AI Agents are not generic conversational interfaces, but precision instruments crafted to solve complex problems within their designated expertise, whether it's technical support, sales consultation, customer service, or strategic analysis. By combining deep domain knowledge with advanced reasoning capabilities, AI Agents can break down intricate challenges, generate context-aware solutions, and interact with users in a manner that mimics expert human professionals. ## New Agent As goal-oriented systems, AI Agents have reasoning capabilities that allow them to execute actions based on information provided by users. The following fields define how the AI Agent is positioned and what responsibilities it holds, influencing every interaction and decision. Creating a new AI Agent involves **three steps:** 1. [General information](#general-information) 2. [Skills](#skills) 3. [Preferences](#preferences) ## General information

AI Agent General information step

### Role A well-defined **Role** creates clarity about what users can expect from the AI Agent and establishes the framework for all its capabilities, whether it's serving as a customer support specialist, a technical troubleshooter, or a creative assistant. Beyond a simple description, the Role functions as a routing signal consumed by the Supervisor, combined with the Goal to determine which AI Agent should handle each request. For this reason, a precise and unambiguous **Role** directly improves the system’s ability to route requests accurately and ensure proper resolution. #### ✅ What to include * **Define a clear problem domain.** A Role must represent one clearly defined type of problem the AI Agent is responsible for solving. For instance: Email delivery troubleshooting specialist; * **Maintain mutual exclusivity**. Roles must not overlap, so if two AI Agent reasonably handle the same request, the Roles are incorrectly defined; * **Calibrate granuality**, where it should reflect stable operational domains, clear problem clusters and real routing categories used by the Supervisor. Roles should not be too broad (for instance: Customer support agent) or too narrow (for example: password reset for Outlook on Android agent). #### ❌ What not to include * **Don't describe behavior or tone**. The Role does not define *Communication style*, *Personality, Voice* or *Interaction strategy*. That belongs to **Persona** and **Instructions**, not Role; * **Don't encode business logic into Role**. The Role must not contain prioritization logic, segmentation rules, or workflow constraints. For instance: Agent that handles VIP customers first. {% hint style="info" %} The Role defines *what problem is owned*, not *how decisions are prioritized*. {% endhint %} ### Goal The **Goal** defines the primary objective an AI Agent is responsible for achieving through its interactions. It establishes: * The outcomes the agent must deliver; * The responsibilities it owns; * The problem space it is authorized to handle. The Goal defines *what the AI Agent exists to accomplish* — not how it behaves, but what it is accountable for within the system. A clearly defined Goal helps the Supervisor Agent to make intelligent choices when faced with ambiguity, ensuring that every conversation advances toward the right AI Agent. {% hint style="info" %} **This field is crucial for proper task delegation** - the Supervisor uses the information in Role and Goal to determine which AI Agent should handle each user request. {% endhint %} #### ✅ What to include * Specific tasks and responsibilities the AI Agent can handle; * Key capabilities and services it provides; * Domain expertise or specialized knowledge areas; * Clear boundaries of what the AI Agent does and doesn't do; * A well-structured Goal describing the use case the AI Agent is expected to handle. #### ❌ What not to include * Avoid vague or generic Goals such as “help users” or “provide support”; * Do not use terms that lead the AI Agent to handle every request, even outside its expertise. This can compromise proper routing to other AI Agents; * Avoid creating similar Goals across AI Agents, as this can reduce the Supervisor’s routing accuracy. #### 🧩 Well-structured Goal examples Technical Support Agent goal example: > *Diagnose and resolve user Wi-Fi connectivity issues by identifying device and network conditions, guiding users through structured troubleshooting steps, and confirming resolution. Escalate cases when connectivity cannot be restored through standard diagnostics.* Voyage Advisor Agent goal example: > *Recommend travel destinations and create personalized itineraries based on user preferences, including suggested activities and accommodations. Assist with planning decisions but does not handle bookings or payment processing.* These examples show how a well-defined Goal clearly specifies what the AI Agent does and the type of requests it handles, avoiding generic descriptions. This level of clarity helps the Supervisor determine exactly when to route a request to the AI Agent. {% hint style="info" %} The more specific and well-scoped the Goal is, the more accurately the Supervisor can delegate user requests. {% endhint %} ### Persona The Supervisor default **Persona** can be used, or a specific Persona can be assigned to each AI Agent. Different Personas may be configured for each AI Agent, depending on the use case. ### Instructions While **Role** defines what the AI Agent is, and **Goal** defines what it must achieve, the **Instructions field defines how the AI Agent operates across the conversation.** Instructions describe the AI Agent’s working method. These Instructions help ensure: * Consistency in the AI Agent’s responses; * Compliance with process requirements; * Proper sequencing of actions when interacting with the Supervisor or other AI Agents. {% hint style="info" %} Instructions do **not** define purpose (Goal) or capabilities (Actions). They do **not** define Rules. {% endhint %} #### ✅ What to include When writing AI Agent Instructions, focus on clear, actionable steps and specific constraints relevant to the task. Here’s what you can include: 1. **Step-by-step execution** * Number the steps to make them easy to follow. Example:\ \&#xNAN;*1. Verify if **fetch\_invoice** action has been executed at least once;*\ *2. If not, execute **fetch\_invoice** before **issue\_invoice;***\ *3. Confirm with the user before proceeding to the next step.* 2. **Output formatting rules** * Set character limits for each message; * Define the structure of the reply (for instance: summary + next step, list, table); * Specify if messages should be sent **one at a time** or combined **all at once**. 3. **Protocols and compliance rules** * Any mandatory procedures before moving forward; * Data collection requirements (for instance: *Always ask for the user’s email before sending a confirmation.*). 4. **Closing behavior** * Define how the AI Agent should finalize the conversation for the use case. Example: \ \&#xNAN;*"After completing the task, ask: 'Can I help you with anything else?' And, if not, prompt for feedback."* 5. **Fixed messages:** You can set up standard and/or mandatory communications. * Enclose any fixed messages in quotation marks "like this" to ensure they are always delivered exactly as written. Example: \ \&#xNAN;*If the user says they no longer need help, respond with: "Please rate this service at the end of our interaction."* * When starting say: "Hello! I'm going to help you with `[process]`. First, I need some information..." Upon completion, say: “Process completed! Is there anything else I can help you with?”\ For transitions: “I will now `[next_action]`. Please wait...” {% hint style="info" %} Just keep in mind that scripted text can make dialogue sound a little rigid. {% endhint %} #### ❌ **What not to include** * **Persona or tone of voice:** These are already defined in the AI Agent’s **Persona** or system-level Persona; * **General task description:** This belongs in the **Goal** field; * **Ambiguous or contradictory rules:** Avoid conflicting steps or unclear conditions; * **Unnecessary context**: Keep it relevant to execution, not high-level strategy. Prompt example for a Technical Support Agent: > *Workflow steps (execute in this exact order):* > > 1. *Collect device type, operating system, issue description, and when the problem started.* > 2. *Perform basic connectivity diagnostic, waiting for the user to complete each test before proceeding.* > 3. *Apply the appropriate solution based on diagnostic results.* > 4. *Verify issue resolution with user confirmation.* > 5. *Document solution or escalate if unresolved.*
> > *Response formatting:* > > * *Output must be in HTML; do NOT use Markdown.* > * *Do NOT include numbers or bullet points in messages.* > * *Bold **user actions** using tags.* > * *Limit each message to 200 characters.* > * *Send one instruction per message; do not combine steps.* > * *After each step, always ask: "Did this step work?" before proceeding.*
> > *Mandatory requirements:* > > * *Confirm device type before suggesting any solution.* > * *MUST complete connectivity test before suggesting network solutions.* > * *CANNOT recommend device reset until data backup is confirmed.* > * *REQUIRED: Verify current settings before applying configuration changes.*
> > *Conditional responses:* > > * *IF basic solutions fail → Escalate to advanced diagnostics.* > * *IF multiple devices are affected → Check for network-wide issues.* > * *IF the problem persists after 3 solutions → Escalate to a human technician.*
> > *Fixed closing message:* > > * *When the user no longer needs assistance, output exactly: "Please rate my assistance at the end of this chat."*
> > *Important notes:* > > * *NEVER improvise steps or change their order.* > * *NEVER output additional explanations outside the HTML-formatted instructions.* #### Rules The **Rules** field defines atomic constraints that restrict or enforce the AI Agent’s behavior during task execution. Rules do not describe workflow, they define mandatory conditions, prohibitions, and decision boundaries. While Instructions define how the AI Agent proceeds, Rules define what the AI Agent must or must not do. They ensure: * Compliance with required procedures; * Enforcement of business constraints; * Consistent behavior across scenarios. {% hint style="info" %} Each Rule should be written as a **single, clear statement**, focusing on what must or must not happen in a given scenario. {% endhint %} ## Skills Add **Skills** (resources such as [Actions ](/user-guide/ai-agents/actions.md)and [Knowledge](/user-guide/ai-agents/knowledge.md)) that are already available in the Project. The **AI Agent's Skills** section is where it is defined their capabilities, the tasks they need to perform their duties.\ \ This section complements the Role and Goal fields: those fields specify what the AI Agent does; here, the required Skills are assigned to perform those tasks. {% hint style="info" %} It is important to remember that **Skills determine how the AI Agent should be used**, not the AI Agent itself, except in exceptional cases. Maintaining this structure ensures consistent and controlled behavior. {% endhint %} #### 📝 Good practices * Avoid overloading the AI Agent with too many Skills. If needed, create additional AI Agents to better distribute use cases; * Avoid sharing Skills across AI Agents. This may create conflicts when determining which AI Agent should handle the request.

AI Agent Skills step

## Preferences ### Inherit Supervisor’s Preferences Define how AI Agents inherit the Supervisor preferences in the new inheritance model: **as-is inheritance** or **customized inheritance**. * **As-is inheritance:** the AI Agent inherits the Supervisor Guardrails exactly as defined and stays automatically synchronized with any updates made to the Supervisor; * **Customized inheritance:** the AI Agent inherits the Supervisor Guardrails as a starting point and allows modifications or extensions with Agent-specific configurations.

AI Agent Preferences step

## Agent cell After clicking `Save`, the **Agent cell** — available only in **Agentic** and **Combined** governance types (not available in **NLU Flow** governance) — appears in the **Workspace**. The **Agent cell** is the main executor. It generates responses based on its Goal, Instructions, Persona, and Guardrails after receiving user input. If it cannot respond effectively, the conversation is automatically transferred to a Supervisor. Inside the **Agent cell**, branches define how the Agent handles different scenarios and capabilities: * **Knowledge branch**: groups all collections associated with the Agent. It may include sequential cells to define how retrieved information is processed and presented; * **Action branch**: When an **Action** is linked to an AI Agent, the system automatically creates a dedicated **Action branch** in the **Workspace**. This branch defines how the Action is executed; * The Action runs according to the sequence defined in its branch. Each cell executes in order and contributes to the Action’s outcome (for instance: by calling external services; executing custom logic; or transforming data) before returning a result to the AI Agent. The branch functions as an execution container within the Workspace; * The Action can be extended with: * **Service cells:** to simulate integrations; * **Code cells:** to execute custom logic or process data. * **Error branch**: It is triggered when a request to the AI Agent fails, not when the AI Agent cannot generate a response. In the latter case, the AI Agent routes the interaction to the Supervisor. The **Agent cell** can trigger linked capabilities such as **Knowledge sources** or **Actions**. {% hint style="info" %} The **Agent cell** supports any subsequent cell type except those incompatible with the Agentic type (**intents**, **entities**, and **end cells**). {% endhint %}

Agent cell in the Workspace. The cell itself can represent an Agent flow.

--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.conversational-ai.syntphony.com/user-guide/ai-agents/ai-agents.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.