Table of Contents

• Overview
• Why UnisonAI?
• Installation
• Core Components
• API Keys
• Parameter Reference Tables
• Usage Examples
• FAQ
• Contributing And License

UnisonAI

Orchestrate the Future of Multi-Agent AI

---

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

What is UnisonAI?

Python framework for building and orchestrating AI agents with A2A communication.

When should I use a Clan?

For complex, multi-step tasks requiring specialized agents working together.

Can I add custom LLMs?

Yes! Extend BaseLLM to integrate any model provider.

What are tools?

Reusable components that extend agent capabilities. Create them with the @tool decorator or the BaseTool class.

How do I manage API keys?

Use environment variables or pass directly to the LLM constructor.

---

Contributing

Author: Anant Sharma (E5Anant)

PRs and issues welcome!

Open Issues • Submit PRs • Suggest Features

---