Untitled

Introduction

Creating an Agent is made of back and forth iterations between the Agent itself and the functions that are attached to that Agent. These iterations are fueled by:

• Prompting the Agent and attaching Functions to it, which you can imagine as tools the Agent will call (such as search in a knowledge base, calling an API, calling another Agent, etc)
• Testing the Agent in Playground, and observing that it does trigger the right functions at the right time
• Creating Evaluations (for both the Agent and the Functions). An evaluation is a scenario which you can run with each new configuration of your agent, to make sure it behaves properly (more about this in the right section. We recommend creating the Evaluations as they arise, rather than at the end of your project!

In this article, we will describe the different parameters that are present in the Agent configuration page. For a quick overview of how to create an Agent from scratch and attach it a first function, we suggest you start with one of the tutorials.

Creating a new Agent

The first thing you want to do when using Squadra is creating a new Agent, going to Agents\\+New. Name your agent.

Main Parameters (models & promtps)

Here are the main parameters:

• Model: The model and provider you choose to use, among the usual suspects (OpenAI, Mistral, Google, etc). Bigger models are usually more accurate but more expensive, and also slower. Models such as gpt 4o-mini are already good enough for a lot of tasks, and more sober in terms of resources!
• Advanced setting: Unless you know what these means, we recommend you don’t touch them!
• Main prompt: There is a lot of literature about how to write good prompts; we recommend this guide from OpenAI https://platform.openai.com/docs/guides/prompt-engineering. Generally speaking, our recommendation aligns with this quote from the 17th-century man of letters Nicolas Boileau “ce qui se conçoit bien s’énonce clairement” (”What is well conceived is clearly expressed”). If your instructions are written in prose that leaves no room for ambiguity, the agent should be able to follow them successfully.
• First message (optional): This is the pre-filled message that your agent will send to the user when a conversation starts.

Once these are set, you can already converse with your agent: it will appear in the Agents list on the left, as well as in Agents > Playground.

Playground

Go to Agents > Playground to start conversing with your agent, and see how it reacts to messages, whether it queries the right functions, etc. You can start as soon as you have defined a new Agent and its prompt !

Below is an example conversation with an Agent (the full tutorial for this Agent can be found as the first tutorial in this documentation):

You can see after the User question, and before answering:

• the Agent triggered a Function call
• the Agent received a response from that function
• then it crafted its answer based on this response.

If you click the JSON button, either for the Function call or the Function response, you can decompose the content of these calls and responses.

These are explained in more details in the Functions section.

Functions Calling & Function Hooks

Functions are independent from Agents. They can be attached to several agents, or even triggered independently. See Section Functions for more details about functions.

Agents use functions in 2 distinct ways:

• Function calling: this is when the LLM dictates which function to call at which time
• Function hooks: this is when the agent creator specifies that a function must run at specific times and conditions. An example of function hook is a function that retrieves the profile data of the user so it can be injected in the agent’s system prompt. For example: “You are a helpful assistant. The user is named {{context.user.name}} and speaks {{context.user.lang}}”.

Empower your Agent with Function calling

Once you have configured functions, attach them to the Agent to make sure the agent can call these functions.

Function Hooks

Go fo Agents, then add step at the bottom to create a new hook.

Here is an example for a function hook. This hook is configured to get external user information (such as their latest social media posts) each type the user sends a message, and convey the information to the agent.

Here is an explanation of the parameters:

• Hook type: “Before a user message” means that each time a user sends a message, before this message is conveyed to the agent, the hook will be activated so that the “hooked” function is called, so that the agent has at its disposal in the context the information form the function before it starts answering the user. Other types are “before the first user message”, which means the hook will be triggered at the very beginning of the conversation, and “After an agent message”, which means the Agent calls a function only after it has replied to the user (which would make sense combined with a trigger, when the agent sends messages autonomously – see below).

• Inputs: if the function called by the hook requires an input (see the page Functions for more details), this is where you can fill it. For Example, if your function getUser needs the string userID as an input, and that userID is actually the user email, available in the context of the agent (see section Context below for an explanation of variables available in the context), you will write this kind of json object:

  {
  	"userID": user.email
  }
  

• Results action: these are the various ways in which the function results can be injected for the Agent to use. Merge results in context (temporarily) means that the function results will be injected for the agent in the context of the conversation, as any other message from the agent or the user, so in the long run it might be diluted in the general context. Merge results in context (permanently) means that this result will be logged in the Context database; see section Context below for more explanations. Report conversation based on the results might be used to create supervision reports for the admin to review the conversation. If the function renders non-null result, a report is generated that flags the problematic conversations to the admin, which can be seen in the conversations explorer in the module Monitoring > Conversations.

Context

Context of an agent: The context of an agent is a data structure that may be accessed in the prompts or functions of this agent (via template or data transformation syntax). The context is constructed from various sources:

• Base context: current date, time, datetime, user (and anonUser, if any)
• Temporary context: data submitted in the chat request or generated by a function hook or trigger.
• Persistent context: data persisted in the scope of the conversation (may be submitted via the API or generated by a function hook or trigger).

To use this context, you can summon context from various sources via curly brackets {{object}}. Here is an example Agent prompt using various variables from the context:

You are a helpful assistant.
Current date is {{date}}
You will be discussing with user {{{json context.profile}}}
His email is {{user.email}}

Let’s look at the various elements of this prompt:

• The format of this form is Handlebars, a standard for writing javascript forms. With Handlebars, objects are between two curly brackets {{object}}.
• {{date}} is available from the general context. The context includes: dateTime: Timestamp in the Europe/Paris timezone, for example: '2024-12-09 11:20:46' date: '2024-12-09' time: '11:20:46'
• For users logged in Squadra, the following parameters are accessible: {{user.name}}, {{user.id}}, {{user.email}} .
• For anonUsers, meaning users that are not logged in Squadra (for example, if your agent is deployed in Whatsapp or in Discord and answers from there, your users will never log into the Squadra app; they are therefore anonUsers from our point of view, even if they might be logged in the client application), depending on the client, different data might be available. For example in Whatsapp, {{anonUser.ID}} will render the phone number of the user; {{anonUser.name}} will render the name in Whatsapp.
• The Context is a database inherent to each conversation. Context can be modified by three things: function hooks, triggers, and the context endpoint in the API, through which the client can write custom Context for each agent.
• In this example, the {{context.profile}} element has been logged by the function hook displayed in the Section Functions Calling & Function Hooks that called a function named api-call/hook_get_user. This function includes the following post-processing script which renders a profile object, which can in turn be called through the context.
• The options json in {{{json context.profile}}} means that the agent must format the following json object context.profile in the json format. The other option available would be yaml . Triple curly brackets {{{object}}} are used to escape characters.

Finally, other variables are available:

• env.variables, which are defined in module Development > Environment. Please refer to that part of the documentation for more details
• conversation variables, which includes conversation.id , conversation.messages and  conversation.agent: this allows access to previous messages and function calls / responses in the conversation.

Triggers

<aside> 🏗️

Under Construction

</aside>

Triggers are available at Agents > Triggers .

An agent trigger is a functionality that makes an agent start or continue a conversation with a user (rather than letting the user take the initiative).

A trigger configuration includes:

• an agent
• a user (and anonUser if any)
• How to generate the agent message (it may be hard-coded or generated
• An optional function: when configured, this function can override the user and message. This is very powerful, because the function may return an array of users to send customized messages to many users simultaneously.

Scheduling :

Example: let’s say you want to schedule a trigger to run each day. After you have configured a trigger, you may schedule it to run regularly. Go to Agents > Triggers and in the table click on “Schedule”. A form will appear asking for a Cron string. This is a standard format for specifying a recurring date and time. There are many tools that can help you generate a cron string in the correct format (eg. https://crontab.guru/). For example “0 0 * * *” means “run every day at midnight.

Evals

<aside> 🏗️

Under Construction

</aside>

An agent eval is a structured testing scenario where an AI agent interacts with predefined user inputs across multiple exchanges, simulating real-world use cases. The agent must produce correct outputs and trigger specified actions to pass the test. Evals are run in batches, enabling regression testing to validate that new configurations or updates do not degrade the agent's performance.

☰ On this page…