Create Agents AI

Overview

Create Agents AI (createagents) is a modular and extensible Python framework designed to build intelligent, testable conversational agents. Built on Clean Architecture and SOLID principles, it provides strict provider isolation, automatic conversation history, tool integration, metrics export, and an interactive terminal CLI.

Project status: Beta. APIs and behavior may evolve as the project matures.

Key Capabilities

• Clean Architecture: Inward dependency flow with business logic isolated from external frameworks and providers.
• Pluggable Providers: First-class support for OpenAI and Ollama (local and private on localhost).
• Extensible Tools: Standard BaseTool interface with built-in date/time and secure local file reading.
• Contextual History: Automatic multi-turn conversation memory management.
• Metrics Export: Export interaction metrics to JSON and Prometheus formats without requiring external daemons.
• Silent by Default: Zero unsolicited console logging until explicitly enabled via LoggingConfig.
• Type Safety & Quality: The codebase is type-checked with mypy, verified with Ruff and Bandit, and covered by automated test gates.

Supported Providers

Installation

For End Users

Install the latest published package from PyPI:

# Standard installation
pip install createagents

# With file-reading tools (PDF, Excel, CSV, Parquet)
pip install 'createagents[file-tools]'

For Development and Contributors

Clone the repository and use uv for reproducible dependency resolution:

git clone https://github.com/jordanestralioto/Create-Agents-AI.git
cd Create-Agents-AI

# Install all locked dependencies
uv sync --locked

# Or include optional file-tools
uv sync --locked --extra file-tools

See CONTRIBUTING.md and the Developer Contribution Guide for full instructions.

Quick Start

1. OpenAI Agent

Set your API key:

export OPENAI_API_KEY="your-openai-api-key-here"

Note: Replace "YOUR_MODEL" below with your desired OpenAI model identifier.

import asyncio
from createagents import CreateAgent


async def main() -> None:
    # Initialize the agent
    agent = CreateAgent(
        provider='openai',
        model='YOUR_MODEL',
        instructions='You are a helpful and concise software engineering assistant.',
    )

    # Send a message
    response = await agent.chat('How do I structure a Python project?')
    print(response)


if __name__ == '__main__':
    asyncio.run(main())

2. Local Ollama Agent

Ensure your Ollama server is running and pull your preferred model:

# Pull model and start the Ollama server
ollama pull YOUR_OLLAMA_MODEL
ollama serve

Note: Replace "YOUR_OLLAMA_MODEL" with a locally installed model name.

import asyncio
from createagents import CreateAgent


async def main() -> None:
    # Initialize local Ollama agent
    agent = CreateAgent(
        provider='ollama',
        model='YOUR_OLLAMA_MODEL',
        instructions='You are a local private assistant.',
    )

    response = await agent.chat('Explain Clean Architecture in two sentences.')
    print(response)


if __name__ == '__main__':
    asyncio.run(main())

Built-in Tools

Create Agents AI includes standard tools out of the box and supports custom extensions through BaseTool.

Using Tools

import asyncio
from createagents import CreateAgent


async def main() -> None:
    agent = CreateAgent(
        provider='openai',
        model='YOUR_MODEL',
        tools=['currentdate'],
    )

    # The agent automatically determines when to call the tool
    response = await agent.chat(
        'What is the current time in America/New_York?'
    )
    print(response)


if __name__ == '__main__':
    asyncio.run(main())

Configuration & Environment

Environment Variables

Agent Runtime Configuration

from createagents import CreateAgent

config = {
    'temperature': 0.7,  # Allowed range: 0.0 to 2.0
    'max_tokens': 1500,  # Positive integer
    'top_p': 0.9,  # Allowed range: 0.0 to 1.0
    'stream': False,  # Enable token-by-token streaming
}

# Provider-specific reasoning/thinking options:
# Ollama: think=True/False or "low"|"medium"|"high"
# OpenAI: think="low"|"medium"|"high" (on supported reasoning models)

agent = CreateAgent(
    provider='openai',
    model='YOUR_MODEL',
    instructions='Be technical and concise.',
    config=config,
    history_max_size=20,
)

Logging & Metrics

Silent Library Logging

The library installs a NullHandler and remains completely silent by default. Consumers can opt into logging during development or configure handlers explicitly:

import logging
from createagents import LoggingConfig

# Enable console logging for development
LoggingConfig.configure_for_development(level=logging.INFO)

Metrics Export

Collect and export interaction metrics (latency, token counts, model calls) to structured JSON or Prometheus format strings and files:

from createagents import CreateAgent

agent = CreateAgent(provider='openai', model='YOUR_MODEL')

# Retrieve metrics objects
metrics = agent.get_metrics()

# Export metrics to JSON or Prometheus format files/strings
agent.export_metrics_json('metrics.json')
agent.export_metrics_prometheus('metrics.prom')

Note: The package exports metrics formatted for Prometheus scraping or file collectors; it does not run a background Prometheus HTTP server or monitoring daemon.

Architecture

Create Agents AI is structured around strict Clean Architecture boundaries:

┌────────────────────────────────────────────────────────────┐
│ MAIN (Composition Root & Facade)                           │
│ CreateAgent: src/createagents/main/facade/client.py        │
│ AgentComposer: src/createagents/main/composers/            │
└──────────────────────────────┬─────────────────────────────┘
                               │ wires and injects dependencies
        ┌──────────────────────┼──────────────────────┐
        │                      │                      │
        ▼                      ▼                      ▼
┌───────────────┐   ┌────────────────┐   ┌────────────────────────┐
│ PRESENTATION  │   │ APPLICATION    │   │ INFRASTRUCTURE         │
│ CLI Terminal  │──▶│ Use Cases      │◀──│ Adapters & Factories   │
│ Application   │   │ DTOs & Ports   │   │ (OpenAI, Ollama, Tools)│
└───────────────┘   └───────┬────────┘   └────────────────────────┘
                            │ depends only on
                            ▼
                    ┌────────────────┐
                    │ DOMAIN         │
                    │ Entities/Rules │
                    └────────────────┘

• Domain: Pure business entities, value objects, and domain exceptions. No external dependencies.
• Application: Use cases, DTOs, and interface ports (e.g. ChatRepository). Depends solely on Domain.
• Infrastructure: Concrete adapters implementing application ports (OpenAI, Ollama, tools, logging, metrics).
• Presentation: Interactive terminal CLI consuming the application facade lazily.
• Main: Composition root (AgentComposer) wiring concrete adapters into use cases, and the public CreateAgent facade.

Read the Architecture Developer Guide for full architectural details.

Documentation Directory

The complete documentation suite is published and accessible:

English Documentation (Primary)

• User Guide: Installation • Basic Usage • CLI Usage • Streaming Guide • Examples • FAQ
• Developer Guide: Architecture • CLI Architecture • Async Guide • Logging Guide • Technical Examples • How to Contribute
• Reference: API Reference • Streaming API • Metrics API • Tools • CLI Commands

Portuguese Documentation

• Portuguese Documentation Home

Governance & Community

• Contributing: Please review CONTRIBUTING.md and the Contribution Guide.
• Security: For vulnerability reporting, please see SECURITY.md.
• Code of Conduct: Community standards are defined in CODE_OF_CONDUCT.md.
• License: Released under the MIT License.

Support & Contact

• Maintainer: Jordan Estralioto
• Email: estraliotojordan@gmail.com
• Security: Please report security vulnerabilities privately according to SECURITY.md.