Anatomy of an Agent: Active Agents
Unlike Passive Agents that react to user interaction, Active Agents are designed to proactively initiate actions. They act based on predefined rules and conditions — such as state changes in a system or scheduled events — without requiring a user to start the conversation.
General Structure
The definition of an Active Agent is also done in the agent_definition.yaml file, but its structure focuses on rules and pre_processing instead of tools.
agents:
my_active_agent: # <--- Active agent slug
name: "Order Status Notifier"
description: "An agent that proactively notifies customers about their order status."
rules:
status_aprobado:
display_name: "Approved Status"
template: "template_status_aprobado"
start_condition: "When the order status is 'approved'"
source:
entrypoint: "main.StatusAprovado"
path: "rules/status_aprobado"
status_facturado:
display_name: "Invoiced Status"
template: "template_status_facturado"
start_condition: "When the order status is 'invoiced'"
source:
entrypoint: "main.StatusFacturado"
path: "rules/status_facturado"
pre_processing:
source:
entrypoint: "processing.PreProcessor"
path: "pre_processors/processor"
result_examples_file: "result_example.json"
Rule Definition (rules)
The rules section is a dictionary that defines the triggers that activate the agent’s actions. Each key within rules is a slug or unique ID for each rule.
rules:
status_aprobado: # <--- This is the rule slug
display_name: "Approved Status"
template: "template_status_aprobado"
start_condition: "When the order status is 'approved'"
source:
entrypoint: "main.StatusAprovado"
path: "rules/status_aprobado"
Rule Properties
display_name(string): The readable name for the rule, displayed in the platform interface.template(string): The message template used when the rule is triggered.start_condition(string): A natural-language description of the condition that must be met for the rule to activate.source(dict): Defines the Python code executed when the rule is triggered.entrypoint:Entry point in the formatfilename.ClassName(e.g.,main.StatusAprovado).path: Directory path containing the rule’s code.
Data Pre-Processing (pre_processing)
This section (optional but very powerful) defines a logic step that runs before the rules are evaluated. It’s useful for transforming, enriching, or preparing data.
pre_processing:
source:
entrypoint: "processing.PreProcessor"
path: "pre_processors/processor"
result_examples_file: "result_example.json"
Pre-Processing Properties
source(dict): Defines the code for the pre-processing logic.entrypoint: The class and method for pre-processing (e.g.,processing.PreProcessor).path: The path to the directory containing the pre-processing code.
result_examples_file(string) (Required): Path to a JSON file containing examples of the pre-processing output.
This file is essential for the platform to understand the structure of the data the rules will handle.
Example File Format (result_example.json)
The result examples file must be an array of JSON objects, where each object represents a possible scenario or test case.
[
{
"urn": "tel:+5511999998888",
"data": {
"pedido_id": "12345",
"status_actual": "aprobado",
"cliente_nombre": "Ana"
}
},
{
"urn": "tel:+5521888889999",
"data": {
"pedido_id": "67890",
"status_actual": "enviado",
"cliente_nombre": "Carlos",
"codigo_rastreo": "BR123456789"
}
}
]
urn: A unique identifier for the contact (e.g., a phone number in E.164 format or a user ID).data: An object containing the relevant data for that specific example.
The structure of this object depends on the agent’s requirements.
Suggested Folder Structure
To keep the project organized, it’s recommended to separate the logic for rules and pre-processing into their respective folders.
your-project/
├── rules/
│ ├── status_aprovado/
│ │ ├── main.py
│ │ └── requirements.txt
│ └── status_enviado/
│ ├── main.py
│ └── requirements.txt
├── pre_processors/
│ └── processor/
│ ├── processing.py
│ └── requirements.txt
├── agent_definition.yaml
└── result_example.json
