> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognigy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build Klara, a customer service agent

> Build Klara, a customer service agent, with a brand persona, instructions, a skill, tools, and guardrails. Test it in the Interaction Panel.

> [!NOTE]
>
> **Beginner** · 45 min · Cognigy

In this tutorial, you learn how a brand persona, instructions, a skill, tools, and guardrails work together in one agent. It is for beginners who build their first customer service agent. You build Klara, an agent that helps customers of the fictional company ACME Express collect a shipment from a service point.

## What you will build

Klara greets customers, finds service points for their shipment, and offers to email the service point details.

You build Klara from the following parts:

| Part | Where you set it | What it does in Klara |
| - | - | - |
| Brand persona | **Brand persona** on the **Configuration** tab | Defines how Klara sounds: professional, calm, and dependable. You define a brand persona once in the project, and agents select it. |
| Instructions | **Instructions** on the **Configuration** tab | Define Klara's identity, greeting, scope, and language. They apply to every conversation. |
| Skill | **Skills** tab | Holds the steps for one task, for example, collecting a shipment from a service point. Klara loads the skill only when the customer asks for it. |
| Tools | **Tools** tab | Let Klara act. One tool finds service points and one sends a confirmation email. Each tool runs a flow. |
| Guardrails | **Guardrails** tab | Set safety instructions and decide which contact profile data Klara can use. |

## Prerequisites

Complete the following prerequisites:

* [A Cognigy organization](https://docs.cognigy.com/ai/administer/installation/access-to-cognigy-ai.md).
* A large language model (LLM) in the project. When you create the agent, Cognigy selects the project's default model in the **Language model** section. If the section says that no LLMs are configured, add one first. See [LLMs](https://docs.cognigy.com/ai/agents/develop/gen-ai-and-llms/llms).

## Limitations

* The tool flows return sample data. In a real project, replace the sample data with a call to your own shipment system.
* The Send Confirmation Email tool doesn't send an email. Its flow returns a sample result.

## Steps for this process

**1. Create a project**

A project holds the agent, its flows, and its brand persona.

1. On the Cognigy home page, next to **Projects**, click the plus icon. The **New Project** dialog opens.
2. In the **Project Name** field, enter `Klara Tutorial`.
3. Click **Start empty**. The project opens on the page for agents.

![The New Project dialog with the project name Klara Tutorial and the buttons Start empty and Create with AI Assistant.](https://mintcdn.com/cognigy-15abf2ba/E7J_TZl63DS6FFRh/_assets/tutorials/klara/new-project-dialog.webp?fit=max\&auto=format\&n=E7J_TZl63DS6FFRh\&q=85\&s=88cf02d6310db3f9559962ae92cf92f1)

**2. Create the agent**

1. Click **Add agent**. The **Create new agent** page opens.
2. In the **Agent name** field, enter `Klara`.
3. In the **Role** field, enter `Customer Service Assistant`. In Cognigy 2026.23, this field is called **Job**.
4. Select an avatar.
5. In the **Instructions** field, enter the following text:

   ```text theme={null}
   #Identity
   Your name is Klara. ACME Express is the company you work for, not your name. You handle ACME Express customer service by voice and web chat.

   #Greeting
   In your first message only, greet with exactly "Hi, I'm Klara from ACME Express. How can I help you today?" After your first reply, never introduce yourself or repeat your name. If the customer says hi again later, reply "How can I help you?" or continue where you left off.

   #What you help with
   Finding ACME Express Service Points for a shipment, including whether each one is open, and, on request, emailing the service point details to the customer. Use the service-point-redirect skill. It contains the steps.

   You can't track or verify shipments, reschedule deliveries, book or redirect a delivery, search the web, or hand over to a human advisor. If the customer asks for any of these, or for anything else outside your scope, say you can't help with that here and don't promise anything further.

   #Language
   Answer in the language the customer writes or speaks. Keep answers short, because customers can hear them by voice.
   ```

   The instructions name the skill, so Klara knows when to use it. They also state what Klara can't do, so Klara doesn't promise it.

Keep the page open. You set the brand persona in the "Create the brand persona" step, before you save the agent.

**3. Create the brand persona**

1. Under **Brand persona**, click the edit icon next to the selected persona. In a new project, this is the default persona **NiCE**, which Cognigy creates when the project has none. The **Edit brand persona** page opens.

2. In the **Name** field, enter `ACME Express`.

3. In the **Description** field, enter the following text:

   ```text theme={null}
   You speak on behalf of ACME Express, an international express delivery company. Your voice is professional, calm, and dependable. Customers come away feeling their shipment is in safe hands. You're precise and to the point, warm without being casual, and you never overpromise. You rely only on ACME Express systems and published information, and you say so plainly when you don't know something.
   ```

4. Under **Speaking style**, keep the **Response completeness** slider at **Balanced** and the **Formality level** slider at **Professional**.

5. Click **Save changes**. The **Create new agent** page opens again.

6. Click **Save**. A message confirms that the changes are saved.

![The Create new agent page with the name Klara, the role, the instructions, and the brand persona ACME Express.](https://mintcdn.com/cognigy-15abf2ba/E7J_TZl63DS6FFRh/_assets/tutorials/klara/create-agent-form.webp?fit=max\&auto=format\&n=E7J_TZl63DS6FFRh\&q=85\&s=2e356413562793f9f178a738d407512e)

> [!TIP]
>
> Keep the roles separate. The brand persona describes the voice of the company and can be reused. The instructions describe the job of this one agent.

**4. Create the find service points tool and its flow**

A tool lets Klara fetch data or act. This tool runs a flow that returns the service points for a shipment.

1. Go to the **Tools** tab and click **Add tool**.

2. In the **Add to this agent** window, on the **System tools** tab, select **Execute Tool Flow**. The **Create new tool** page opens.

3. In the **Name** field, replace the default name with `Find Service Points`.

4. In the **Description** field, replace the default text with the following text. Klara reads the description to decide when to call the tool and how to use the result.

   ```text theme={null}
   Finds ACME Express Service Points in the destination city of a shipment, with opening status. Call when the customer wants to collect the shipment instead of home delivery. Returns ok, city, and service_points: a list of {id, name, address, opening_hours, open_now, closes_at}. Mention whether each point is open and when it closes. Only offer service points from this list.
   ```

5. Click the **Select flow** list and select **Create new flow**. A message confirms that the tool is created, and the flow opens. The flow contains a **Tool Result** node.

6. Under **Start**, click the plus icon, search for **Code**, and select it. The **Code** node appears above the **Tool Result** node.

7. Click the **Code** node and enter the following code. It stores sample service points in the Context.

   ```javascript theme={null}
   // Store the sample service points
   context.spAnswer = JSON.stringify({
     ok: true,
     city: "Singapore",
     service_points: [
       { id: "SG-001", name: "ACME Express Service Point Central", address: "12 Example Street, Singapore", opening_hours: "Mon-Sat 09:00-19:00", open_now: true, closes_at: "19:00" },
       { id: "SG-002", name: "ACME Express Locker Harbor", address: "8 Sample Avenue, Singapore", opening_hours: "Daily 00:00-23:59", open_now: true, closes_at: "23:59" }
     ]
   });
   ```

8. Click **Save Node**.

9. Click the **Tool Result** node. In the **Tool Answer** field, enter `{{context.spAnswer}}`, and click **Save Node**. The **Tool Result** node sends the content of this field back to Klara.

   ![The tool flow with a Start node, a Code node, a Tool Result node that returns context.spAnswer, and an End node.](https://mintcdn.com/cognigy-15abf2ba/E7J_TZl63DS6FFRh/_assets/tutorials/klara/tool-flow.webp?fit=max\&auto=format\&n=E7J_TZl63DS6FFRh\&q=85\&s=1ac426a2e4d16b3f61563bcdd392d9bd)

> [!NOTE]
>
> In your own project, replace the **Code** node with an **HTTP Request** node that calls your shipment system. The parameters that Klara fills are available in the flow as `{{input.data.toolArgs.<name>}}`, for example `{{input.data.toolArgs.waybill}}`. Then use a **Code** node to shape the response before the **Tool Result** node. Make sure every path of the flow reaches a **Tool Result** node. Otherwise, Klara receives `The flow finished without returning an answer.` instead of your data.

**5. Add the waybill parameter**

Parameters are the inputs that Klara collects from the conversation and sends to the flow.

1. At the top of the flow editor, click the back arrow next to the flow name. The **Tools** tab of the agent opens. Click **Find Service Points**.
2. Under **Parameters**, click **Add**.
3. In the **Name** field, enter `waybill`.
4. In the **Description** field, enter `The 10-digit waybill number of the shipment, digits only.`
5. Keep the type **Text**, and click **Save changes**.

![The Edit tool page for Find Service Points with the description, the selected flow, and the waybill parameter.](https://mintcdn.com/cognigy-15abf2ba/E7J_TZl63DS6FFRh/_assets/tutorials/klara/find-service-points-tool.webp?fit=max\&auto=format\&n=E7J_TZl63DS6FFRh\&q=85\&s=3c2ebdbf8f2cdc2cfded6e4addf5666d)

**6. Create the send confirmation email tool**

Create a second tool and its flow in the same way as the first tool.

1. Go to the **Tools** tab, click **Add tool**, and select **Execute Tool Flow** on the **System tools** tab.

2. In the **Name** field, replace the default name with `Send Confirmation Email`.

3. In the **Description** field, replace the default text with the following text:

   ```text theme={null}
   Sends an ACME Express confirmation email to the email address on file for the shipment. Call only after the customer clearly agrees to receive the details by email. Pass reference (the waybill number) and details (one sentence: the service point name, address, and opening hours). Returns ok, sent_to (masked email address), and subject.
   ```

4. Select **Create new flow**. The flow opens with a **Tool Result** node.

5. Under **Start**, click the plus icon and add a **Code** node with the following code, then click **Save Node**:

   ```javascript theme={null}
   // Store the sample email result
   context.emailAnswer = JSON.stringify({ ok: true, sent_to: "c***@example.com", subject: "Your ACME Express service point details" });
   ```

6. Click the **Tool Result** node, enter `{{context.emailAnswer}}` in the **Tool Answer** field, and click **Save Node**.

7. At the top of the flow editor, click the back arrow next to the flow name, and on the **Tools** tab, click **Send Confirmation Email**. Under **Parameters**, click **Add** for each of the following parameters, enter its name and description, and keep the type **Text**:

   | Name | Description |
   | - | - |
   | `reference` | The waybill number of the shipment. |
   | `details` | One sentence with the chosen service point name, address, and opening hours. |

8. Click **Save changes**.

The description tells Klara to call this tool only after the customer agrees. The skill repeats this rule in the "Create the skill" step.

**7. Create the skill**

A skill bundles the instructions for one task with the tools that the task needs. Klara loads the skill only when the conversation matches the skill description. This keeps the main instructions short. The tools in a skill become available when the skill is active. Klara can't call Find Service Points or Send Confirmation Email before it loads the skill, even though both tools are also on the **Tools** tab.

1. Go to the **Skills** tab and click **Add skill**.

2. In the **Skill name** field, enter `service-point-redirect`. Use only lowercase letters, numbers, and hyphens.

3. In the **Description** field, enter the following text. Klara uses the description to decide when to load the skill.

   ```text theme={null}
   Load when a customer wants to collect their shipment from an ACME Express Service Point or locker instead of home delivery, before listing service points or sending any email.
   ```

4. In the **Instructions** field, enter the following text:

   ```text theme={null}
   ## Steps
   1. Ask for the 10-digit waybill number (digits only). If it has fewer or more digits, ask the customer to check it. On voice, read it back in groups, for example 142 859 2406, to confirm.
   2. Call Find Service Points with the waybill.
   3. If ok is false, explain briefly that you couldn't find service points for that shipment and ask the customer to re-check the waybill (maximum 2 attempts). After that, apologize and say you can't help further here.
   4. In chat, list the service points with name, address, and opening hours, and say for each whether it is open. On voice, offer only the first service point that is open. Say its name, spell the ID, for example S-G-0-0-1, and give the address in one sentence. Offer the next one only if the customer asks.
   5. Ask if the customer wants these details sent by email. Only after a clear yes, call Send Confirmation Email with reference set to the waybill number and details set to the chosen service point name, address, and opening hours.
   6. Tell the customer the email was sent to the masked address returned in sent_to.

   ## Rules
   - You can only look up and share service points. You can't book, redirect, or reschedule a delivery. If asked, say you can't do that here and don't promise anything further.
   - Only offer service points returned by Find Service Points. Never invent addresses or opening hours.
   - Never send the email without an explicit yes.
   ```

5. In the **Tools** section, click **Add tool**, select **Find Service Points** and **Send Confirmation Email**, and click **Attach selected**.

6. Click **Save**. A message confirms that the skill is saved.

![The Edit skill page for service-point-redirect with its description, its steps and rules, and the two attached tools.](https://mintcdn.com/cognigy-15abf2ba/E7J_TZl63DS6FFRh/_assets/tutorials/klara/service-point-redirect-skill.webp?fit=max\&auto=format\&n=E7J_TZl63DS6FFRh\&q=85\&s=292ef9c869fc997ee205e313794967da)

> [!TIP]
>
> Write skill steps for the ear as well as the eye. The steps for voice offer one service point at a time and spell out IDs, because customers can't scroll a list they hear.

**8. Check the guardrails**

Guardrails set the safety and privacy boundaries for the agent.

1. Go to the **Guardrails** tab.
2. Under **Safety instructions**, keep the following settings turned on:
   * **Avoid harmful content**
   * **Avoid ungrounded content**
   * **Avoid copyright infringements**
   * **Prevent jailbreak and manipulation**
3. Under **Data privacy**, keep **No profile fields** for **Contact profile information**. Klara doesn't need contact profile data, because in a real project the email tool looks up the address in your system. To personalize answers, select the profile fields that Klara can use.

![The Guardrails configuration page with four safety instructions turned on and No profile fields selected for the contact profile information.](https://mintcdn.com/cognigy-15abf2ba/E7J_TZl63DS6FFRh/_assets/tutorials/klara/guardrails.webp?fit=max\&auto=format\&n=E7J_TZl63DS6FFRh\&q=85\&s=3992c6f9a0c7fdf9ed17d3b936672753)

**9. Test Klara in the interaction panel**

1. Click the chat icon to open the **Interaction Panel**.
2. At the top of the panel, select **Klara** from the list if it isn't already selected, and select **Chat**. To see what Klara does in each turn, click the flask icon (**Advanced mode**) in the header of the **Interaction Panel**.
3. Enter `Hi`. Klara greets you with the exact greeting from the instructions.
4. Enter `I want to pick up my parcel at a service point instead of home delivery`. Klara loads the skill and asks for the 10-digit waybill number.
5. Enter `1428592406`. Klara calls Find Service Points and lists the two sample service points with their opening status.
6. Enter `The locker please, and yes, email me the details`. Klara calls Send Confirmation Email and tells you that the details were sent to the masked address `c***@example.com`.

To check that Klara loaded the skill and ran the tool flows, look at the trace of each turn. For step 4, look for a **Skill loaded** span. For steps 5 and 6, look for an **Execute Tool Flow** span and a **Tool result** span. See [Tracing](https://docs.cognigy.com/ai/agents/test/interaction-panel/tracing.md).

![Animation of the Interaction Panel in Chat mode. Klara greets the customer, asks for the waybill number, lists two service points, and confirms that the email for the locker was sent.](https://mintcdn.com/cognigy-15abf2ba/E7J_TZl63DS6FFRh/_assets/tutorials/klara/test-klara-conversation.webp?fit=max\&auto=format\&n=E7J_TZl63DS6FFRh\&q=85\&s=a6e8f53e40998fc0b23dddead01866b1)

## What's next

You created a project and built Klara from scratch. You gave Klara a brand persona and instructions, a skill for collecting a shipment from a service point, two tools that run flows, and guardrails. You tested the whole conversation in the **Interaction Panel**.

To continue, explore the following pages:

* [Connect a knowledge base](https://docs.cognigy.com/tutorials/cognigy-ai/connect-a-knowledge-base.md) to let Klara answer questions from your content.
* [Add tools with functions](https://docs.cognigy.com/tutorials/cognigy-ai/add-tools-with-functions.md) to call external APIs and run custom code.
* [Voice call](https://docs.cognigy.com/ai/agents/test/interaction-panel/voice-call.md) to test Klara by voice.
* [LLMs](https://docs.cognigy.com/ai/agents/develop/gen-ai-and-llms/llms) to use your own model.