Agent Creation

In Cleo, agents are modular, programmable entities that process input, retrieve context, and execute tasks using tools. Agents are defined by their persona, toolchain, memory, and execution loop. This section provides a full walkthrough of how to create, configure, and extend agents using both static files and dynamic code.

---

What Is an Agent?

An agent in Cleo is a structured interface between natural-language commands and functional execution. Agents:

• Maintain an identity and behavioral context (persona)

• Interpret user input using LLMs or rule-based systems

• Select tools to complete tasks

• Optionally retain memory across sessions

Each agent can be configured to serve different roles — from research assistants to data summarizers, system operators, or API bridges.

---

Basic Agent Configuration

Agents can be declared using JSON or Python. The simplest way to define a new agent is by adding a .json file to the /agents directory.

Example: agents/lex.json

jsonCopyEdit{
  "name": "Lex",
  "persona": "Technical Writer",
  "tools": ["WebScraper", "Summarizer", "PDFReader"],
  "memory": true,
  "voice": false
}

This configuration tells Cleo to instantiate an agent named Lex, who uses web and document tools, retains memory, and does not use voice output.

---

Loading an Agent

You can load an agent by name using the loader function provided in the Cleo core:

pythonCopyEditfrom agents import load_agent

agent = load_agent("lex")
agent.run_loop()

Alternatively, use main.py to boot with the default agent.

---

Creating an Agent in Code

You can also programmatically create and modify agents at runtime. This is useful for agent spawning, dynamic roles, or ephemeral bots.

pythonCopyEditfrom cleo.agent import Agent

agent = Agent(
    name="Nova",
    persona="System Analyst",
    tools=["LogReader", "AnomalyDetector"],
    memory=True
)

agent.run_task("Scan logs for error patterns from April 25–May 1.")

This method gives you fine-grained control over the tool stack, persona, and task scope.

---

Custom Personas

An agent's persona influences how it interprets input and communicates. This can be as simple as a description string, or as complex as a prompt template embedded in logic.

Example personas:

• "Research Assistant with a focus on emerging technologies."

• "Conversational strategist with access to geopolitical databases."

• "Narrative summarizer who writes like a journalist."

You can enhance personas further by adding prompt_prefix, bias tokens, or conversation history shaping.

---

Tool Binding

Agents rely on tools to act. Tools are registered as strings in the agent config, and Cleo binds them to callable objects on load.

Example tool usage inside an agent task loop:

pythonCopyEditresult = self.tools["WebScraper"].run("Recent AI model benchmarks")
summary = self.tools["Summarizer"].run(result)

You can define your own tools in tools/ and reference them by name.

---

Agent Loop Design

Each agent operates in a loop, whether event-driven or interactive. A basic interactive loop looks like this:

pythonCopyEditwhile True:
    task = input(">>> ")
    if task in ("exit", "quit"):
        break
    agent.run_task(task)

Advanced agents may instead operate in a reactive or scheduled loop — checking for triggers, external events, or API inputs.

---

Persistence and Identity

Agents with memory enabled can:

• Recall previous inputs and outputs

• Build context over long sessions

• Learn user preferences and writing styles

Memory backends include FAISS, ChromaDB, and (optionally) local JSON-based logs. See the Memory & Storage section for setup instructions.

---

Versioning and Deployment

Each agent can be version-controlled by saving its config and persona under agents/{name}_vX.json.

Example:

pgsqlCopyEditagents/
├── nova.json
├── nova_v2.json

This enables A/B testing and modular development of specialized personas for different tasks.

---

Summary

Creating an agent in Cleo involves:

1. Defining a persona and capability set

2. Assigning tools

3. Enabling memory (optional)

4. Running tasks in a loop or API-driven interface

Cleo’s architecture is designed to support both minimal agent prototypes and complex, stateful systems.