Table of Contents

• Overview

• Why UnisonAI?

• Installation

• Core Components

• API Keys

• Parameter Reference Tables

• Usage Examples

• FAQ

• Contributing And License

Overview

UnisonAI is a lightweight Python framework for building single-agent and multi-agent AI systems.

• Agent — standalone or part of a clan, with tool integration and conversation history.

• Clan — coordinate multiple agents on a shared goal with built-in A2A messaging.

• Tool System — create tools with @tool decorator or BaseTool class; type-validated, standardized results.

Supports Gemini, OpenAI, Anthropic, Cohere, Groq, Mixtral, xAI, Cerebras, and any custom model (extend BaseLLM).

Quick Start

pip install unisonai-sdk

from unisonai import Agent

from unisonai.llms import Gemini



agent = Agent(

    llm=Gemini(model="gemini-2.0-flash"),

    identity="Assistant",

    description="A helpful AI assistant",

)



print(agent.unleash(task="Explain quantum computing in 3 sentences"))

What Makes UnisonAI Special

Agent-to-Agent (A2A) communication — agents talk to each other as if they were teammates collaborating on complex tasks.

Perfect For

• Complex Research — multiple agents gathering, analyzing, and synthesizing information

• Workflow Automation — coordinated agents handling multi-step processes

• Content Creation — specialized agents for research, writing, and editing

• Data Analysis — distributed agents processing data with different expertise

Core Components

| Component | Purpose | Key Features |

|-----------|---------|--------------|

| Agent | Standalone or clan member | Tool integration, history, inter-agent messaging |

| Clan | Multi-agent orchestration | Automatic planning, task distribution, A2A communication |

| Tool System | Extensible capabilities | @tool decorator, BaseTool class, type validation |

Usage Examples

Individual Agent

from unisonai import Agent

from unisonai.llms import Gemini



agent = Agent(

    llm=Gemini(model="gemini-2.0-flash"),

    identity="Research Assistant",

    description="An AI assistant for research tasks",

)



agent.unleash(task="Summarize the key benefits of renewable energy")

Agent with Tools

from unisonai import Agent

from unisonai.llms import Gemini

from unisonai.tools.tool import tool



@tool(name="calculator", description="Arithmetic on two numbers")

def calculator(operation: str, a: float, b: float) -> str:

    ops = {"add": a + b, "subtract": a - b, "multiply": a * b, "divide": a / b if b else "err"}

    return str(ops.get(operation, "unknown op"))



agent = Agent(

    llm=Gemini(model="gemini-2.0-flash"),

    identity="Math Helper",

    description="An assistant with a calculator tool",

    tools=[calculator()],

)



agent.unleash(task="What is 1500 * 32?")

Multi-Agent Clan

from unisonai import Agent, Clan

from unisonai.llms import Gemini



researcher = Agent(

    llm=Gemini(model="gemini-2.0-flash"),

    identity="Researcher",

    description="Gathers information on topics",

    task="Research assigned topics",

)



writer = Agent(

    llm=Gemini(model="gemini-2.0-flash"),

    identity="Writer",

    description="Writes clear reports from research",

    task="Write polished reports",

)



clan = Clan(

    clan_name="Research Team",

    manager=researcher,

    members=[researcher, writer],

    shared_instruction="Researcher gathers info, Writer produces the report.",

    goal="Write a brief report on AI in healthcare",

    output_file="report.txt",

)



clan.unleash()

Custom Tools

UnisonAI supports two ways to create tools:

1. Decorator-based (Recommended)

from unisonai.tools.tool import tool



@tool(name="calculator", description="Math operations")

def calculator(operation: str, a: float, b: float) -> str:

    if operation == "add":

        return str(a + b)

    elif operation == "multiply":

        return str(a * b)

    return "Unknown operation"

2. Class-based (For complex/stateful tools)

from unisonai.tools.tool import BaseTool, Field

from unisonai.tools.types import ToolParameterType



class Calculator(BaseTool):

    def __init__(self):

        self.name = "calculator"

        self.description = "Math operations"

        self.params = [

            Field(name="operation", description="add or multiply",

                  field_type=ToolParameterType.STRING, required=True),

            Field(name="a", description="First number",

                  field_type=ToolParameterType.FLOAT, required=True),

            Field(name="b", description="Second number",

                  field_type=ToolParameterType.FLOAT, required=True),

        ]

        super().__init__()



    def _run(self, operation: str, a: float, b: float) -> float:

        return a + b if operation == "add" else a * b

API Key Configuration

1. Environment Variables:

   export GEMINI_API_KEY="your-key"
   
   export OPENAI_API_KEY="your-key"
   

2. Direct Initialization:

   llm = Gemini(api_key="your-key")
   

Documentation Hub

Getting Started

• Quick Start Guide — 5-minute setup

• Installation — Detailed options

Core Documentation

• API Reference — Complete API docs

• Architecture Guide — System design

• Usage Guidelines — Best practices

Advanced Features

• Tool System Guide — Custom tool creation

Examples

• Basic Agent — Minimal agent

• Tool Example — @tool decorator & BaseTool

• Clan Example — Multi-agent coordination

FAQ

Contributing

Author: Anant Sharma (E5Anant)

PRs and issues welcome!

Open Issues •

Submit PRs •

Suggest Features