Build AI agents in 4 lines. Orchestrate 63+ agents. Self-evolving. Observable.
LogosAI is a Python framework for building, orchestrating, and evolving AI agents. Create a single agent with minimal code, or build a multi-agent system where agents collaborate, debate, learn from each other, and improve themselves autonomously — with full observability via LogosPulse.
pip install logosai
| LogosAI | LangGraph | CrewAI | OpenAI SDK | OpenClaw | Claude Agent SDK | Google ADK | |
|---|---|---|---|---|---|---|---|
| Agent creation | 4 lines | 30+ lines | 15+ lines | 10+ lines | — | 10+ lines | 10+ lines |
| Tool Use (function calling) | ✅ Auto-inject | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| ReAct (Think→Act→Observe) | ✅ react() |
✅ | ✅ | ✅ | — | ✅ | ✅ |
| Persistent Memory | ✅ PostgreSQL/SQLite + embedding search | ✅ | ✅ | Limited | Local | Limited | Limited |
| LLM Streaming | ✅ Token-by-token | ✅ | — | ✅ | ✅ | ✅ | ✅ |
| Structured Output | ✅ Pydantic schema | ✅ | ✅ | ✅ | — | ✅ | ✅ |
| Error Recovery | ✅ @retry + re-prompt | ✅ | ✅ | ✅ | — | ✅ | ✅ |
| Self-evolution | ✅ Auto-fix + deploy | — | — | — | — | — | — |
| Observability | ✅ LogosPulse (OTel-style traces) | Partial | — | — | — | — | ✅ OTel native |
| Desktop control | ✅ Gmail, KakaoTalk, Notion | — | — | — | ✅ 20+ channels | — | — |
| Browser search | ✅ Real Chrome | — | — | — | ✅ | — | — |
| Agent-to-agent | ✅ call_agent() built-in |
Manual | Manual | — | — | ✅ | ✅ |
| Agent debate | ✅ 5-phase voting | — | — | — | — | — | — |
| Sub-agent spawn | ✅ spawn_agent() |
✅ | ✅ | — | — | ✅ | ✅ |
| Mixin architecture | ✅ Composable mixins | — | — | — | — | — | — |
| Ontology-based routing | ✅ GNN+RL+KG | — | — | — | — | — | — |
| LLM providers | OpenAI, Anthropic, Gemini, Ollama | OpenAI-centric | OpenAI-centric | OpenAI only | Multiple | Claude only | Google-centric |
import asyncio
from logosai import quick_llm
async def main():
answer = await quick_llm("What is the capital of France?")
print(answer) # "The capital of France is Paris."
asyncio.run(main())from logosai import agent, AgentResponse
@agent(name="Joke Agent", description="Tells jokes about any topic")
async def joke_agent(query, context=None, llm=None):
response = await llm.invoke(f"Tell a short joke about: {query}")
return AgentResponse.success(content={"answer": response.content})from logosai import SimpleAgent, AgentResponse
class TranslatorAgent(SimpleAgent):
agent_name = "Translator"
agent_description = "Translates text between languages"
async def handle(self, query, context=None):
translation = await self.ask_llm(f"Translate to English: {query}")
return AgentResponse.success(content={"answer": translation})from logosai import SimpleAgent, AgentResponse
from logosai.acp import SimpleACPServer
class MathAgent(SimpleAgent):
agent_name = "Math Agent"
agent_description = "Solves math problems"
async def handle(self, query, context=None):
answer = await self.ask_llm(f"Calculate: {query}")
return AgentResponse.success(content={"answer": answer})
server = SimpleACPServer(port=9000)
server.add(MathAgent())
server.run()# List agents
curl localhost:9000/jsonrpc -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"list_agents"}'
# SSE streaming
curl -N "localhost:9000/stream?query=3+5&agent_id=math_agent"from logosai import LLMClient
client = LLMClient(provider="google", model="gemini-2.5-flash-lite")
await client.initialize()
response = await client.invoke("Explain async/await in Python")
print(response.content)Supported: openai, anthropic, google (Gemini), ollama
pip install logosai # Core framework
pip install logosai[llm] # + LLM providers (OpenAI, Anthropic, Gemini)
pip install logosai[all] # + All optional dependencies@agentdecorator — 4-line agent creationSimpleAgent— Class-based withask_llm()helperquick_llm()— One-shot LLM callLLMClient— Unified multi-provider client (OpenAI, Anthropic, Gemini, Ollama)LogosAIAgent— Full-featured base with async lifecycle and mixin composition
- SimpleACPServer — Host agents with JSON-RPC + SSE streaming
- Message Bus — Pub/sub with topic routing and priorities
- Workflow Engine — Sequential, parallel, hybrid with enriched data pipeline
- Dynamic Routing — Tag-based auto-discovery, no hardcoded routes
- Data Flow — Previous agent results automatically injected into next agent's query
- Document Search — Semantic search across project docs (LLM-indexed, "where is this info?")
L1: call_agent() — Data passing (query → result)
L2: Debate System — 5-phase workflow negotiation (propose → vote → consensus)
L3: Collaboration — ask_opinion(), share_finding(), request_help()
L4: Learning — share_learning(), get_learnings() (persisted across sessions)
# L1: Call another agent
result = await self.call_agent("internet_agent", "Seoul weather")
# L3: Ask for opinion (not just data — shares reasoning)
opinion = await self.ask_opinion("analysis_agent",
"Is this a seasonal pattern?",
my_analysis={"pattern": "March spike", "confidence": 0.6})
# L4: Share what you learned (persisted for all agents)
await self.share_learning(
pattern="Gmail compose overlay breaks JS selectors",
solution="Add &fs=1 to compose URL",
tags=["gmail", "chrome"])
# L4: Learn from others
learnings = await self.get_learnings(tags=["gmail"])LogosAIAgent is built from five composable mixins, each independently usable:
| Mixin | File | Capabilities |
|---|---|---|
| ToolUseMixin | mixins/tool_use.py |
register_tool(), run_with_tools(), register_tool_object() |
| MemoryMixin | mixins/memory.py |
memorize(), recall(), forget() — embedding hybrid search |
| ReactMixin | mixins/react.py |
react() — Think→Act→Observe loop |
| PlanningMixin | mixins/planning.py |
plan(), plan_stream() — Goal decomposition tree |
| MultiAgentMixin | mixins/multi_agent.py |
call_agent(), delegate(), spawn_agent() |
# Tool Use — 3 ways to register tools
agent.register_tool("calc", "Calculator", calc_func, params) # existing
agent.register_tool_object(Tool(name="calc", category="math", ...)) # new: Tool dataclass
agent.register_tool_object(@tool_decorator(...)) # new: auto-parse signature
# ReAct — Think → Act → Observe loop
result = await agent.react(
"Calculate compound interest: $10K at 8% for 5 years, then convert to KRW",
tools=BUILTIN_TOOLS, tool_executors=BUILTIN_EXECUTORS,
)
# → Thought: "Need to calculate compound interest"
# → Action: calculator(10000 * 1.08**5) → $14,693
# → Thought: "Now convert to KRW"
# → Action: calculator(14693 * 1380) → ₩20,276,340
# → Final Answer: "₩20,276,340"
# Persistent Memory — embedding hybrid search
await agent.memorize("user_pref", "User prefers Korean", importance=0.9)
memories = await agent.recall("user") # Auto-injected into LLM context
# Semantic: query "수도 날씨" finds memory "서울 기온" via cosine similarity
# Goal Decomposition
plan = await agent.plan("Build a web scraper for news articles")
# → Sub-goals: fetch → parse → store → deduplicate → schedule
async for step in agent.plan_stream("Build a web scraper"):
print(step) # Streams decomposition steps in real-time
# Structured Output — enforce JSON schema
from pydantic import BaseModel
class Weather(BaseModel):
city: str
temperature: float
result = await agent.ask_llm_structured("Seoul weather", Weather)
# → Weather(city="Seoul", temperature=22.5)
# Dynamic Sub-Agent — create specialists at runtime
translator = agent.spawn_agent("translator", "Translates text", my_func)
results = await agent.delegate([
{"agent_id": "translator", "query": "Hello"},
{"agent_id": "calculator", "query": "1+1"},
], parallel=True)
# LLM Streaming — token-by-token
async for chunk in agent.ask_llm_stream("Tell me about AI"):
print(chunk, end="")Capabilities: Tool Use · ReAct · Memory (embedding search) · Goal Decomposition · Streaming · Structured Output · Error Recovery · Context Management
Generate professional documents through natural language:
"SpaceX 회사 정보를 PPT로 만들어줘"
→ internet_agent (search) → pptx_generator_agent (generate)
→ PowerPoint opens and builds slides in real-time
"Docker 매뉴얼을 워드로 만들어줘"
→ docx_generator_agent → Word document with tables, charts, metrics
| Feature | Details |
|---|---|
| PPT Generation | 101 themes × 15 layouts, Desktop Native (AppleScript) + python-pptx fallback |
| DOCX Generation | 8 doc_types × 8 themes, Hybrid mode (python-docx tables + Desktop Native text) |
| Google Maps | Place search + directions + interactive map rendering |
| File Search | Spotlight + find + grep — local filesystem search with content matching |
| Capability Protocol | Agent auto-composition via DAG (Level B composite + Level C autonomous) |
OpenTelemetry-style tracing and metrics for every agent execution:
Root Span (agent.process)
├── LLM Span (llm.gemini-2.5-flash-lite) — intent extraction ~120ms
└── LLM Span (llm.gemini-2.5-flash-lite) — response generation ~1.8s
from logosai.utils.pulse_client import PulseClient
# Fire-and-forget — zero overhead (~0.01ms/span)
pulse = PulseClient(endpoint="http://localhost:8095")
await pulse.record_execution(agent_id, query, result, duration_ms)
await pulse.record_llm_call(model, tokens_in, tokens_out, latency_ms)
await pulse.record_span(trace_id, parent_id, name, metadata)Dashboard (port 8096): Execution history · LLM cost tracking · Span tree visualization · User feedback (👍/👎) · Adaptive learning loop
from logosai.evolution import EvolutionSystem, EvolutionConfig
config = EvolutionConfig(enabled=True, llm_provider="google")
evolution = EvolutionSystem(agent, config)
await evolution.enable()Capabilities: Self-Healing · Self-Growing · Self-Evaluation
Safety: Circuit Breaker (3 failures → 1h cooldown) · Confidence Gates · Fix History
pip install logosai-forgefrom logosai_forge import ForgeClient
forge = ForgeClient()
result = await forge.create_agent("Calculate BMI from weight and height")
result = await forge.improve_agent(code, failure_log) # Fix bugs
result = await forge.enhance_agent(code, "add caching") # Add featuresAutonomous evolution loop:
Agent fails → FailureLogger → 30% threshold → FORGE improves
→ Confidence Gate (≥0.95) → RollbackManager backup
→ hot_register (zero-downtime deploy) → EvolutionMonitor tracks
Control your desktop through natural language — 63+ agents, each independent:
desktop_agent (dynamic LLM router — no hardcoded routes)
├── call_agent("kakaotalk_agent") → KakaoTalk messaging
├── call_agent("mail_desktop_agent") → Gmail read/compose/attach
├── call_agent("notion_desktop_agent") → Notion pages/todos
├── call_agent("multi_ai_inquiry_agent") → ChatGPT/Claude/Gemini compare
├── call_agent("auto_report_agent") → Scheduled search + delivery
└── screen_analyzer (lightweight 0.1s + Vision 3s fallback)
| Feature | macOS | Ubuntu |
|---|---|---|
| Gmail read/compose/reply/attach | ✅ | ✅ Chrome CDP |
| KakaoTalk messaging | ✅ AppleScript | ❌ |
| Notion read/create/todos | ✅ Keyboard + Vision | ✅ |
| Multi-AI Inquiry | ✅ App + Chrome | ✅ Chrome |
| Auto Reports (scheduled) | ✅ | ✅ |
| ScreenAnalyzer (lightweight + Vision) | ✅ | ✅ |
| Intent Verification | ✅ | ✅ |
ScreenAnalyzer: Lightweight check first (~0.1s AppleScript/JS) → Vision fallback only when needed (~3s). Intent Verification: verifies all preconditions before irreversible actions. No Trace: closes windows and restores previous app after completion (Cmd+W, not Cmd+Q).
"Every morning at 8am, search Seoul weather and send via KakaoTalk"
"If Bitcoin exceeds $80,000, notify me by email"
Conditional execution · AI summary · Multi-channel (KakaoTalk/Gmail/Telegram)
Web management: http://localhost:8010/auto-reports
54 tests across framework core, Agentic AI, and observability:
pytest logosai/tests/ -v # Framework + Agentic AI tests
pytest logos_pulse/tests/ -v # Observability + tracing testsKey coverage: Tool Use · ReAct · Persistent Memory · Goal Decomposition · Span Tracing · Feedback API · Learning Loop · SSE Bidirectional · Interaction Engine (31 tests + 7 evaluations)
| Guide | Description |
|---|---|
| ACP Protocol | Agent Communication Protocol — endpoints, call_agent(), Auto Reports |
| Building Agentic AI | LLM integration, collaboration, debate, evolution |
| Building an ACP Server | Deploy multi-agent servers with JSON-RPC + SSE |
| Samples | Runnable examples — ResearchAgent, calculator, hello world |
macOS:
curl -fsSL https://raw.githubusercontent.com/maior/logosai-framework/main/install-macos.sh | bashUbuntu / Debian:
curl -fsSL https://raw.githubusercontent.com/maior/logosai-framework/main/install-ubuntu.sh | bashcd ~/logosai
./start.sh # Start all services
./stop.sh # Stop all services
./status.sh # Check what's running| Service | Port | Description |
|---|---|---|
| logos_web | 8010 | Next.js frontend — chat, admin, auto reports, architecture |
| logos_api | 8090 | FastAPI backend — auth, streaming, memory, Telegram bot |
| ACP Server | 8888 | Agent runtime — 63+ agents, self-evolution, L3/L4, Desktop Native |
| LogosPulse API | 8095 | Observability backend — execution traces, LLM metrics, costs |
| LogosPulse UI | 8096 | Observability dashboard — span tree, feedback, learning loop |
| PostgreSQL | 5432 | Database |
Core: Python 3.11+, aiohttp, pydantic, loguru
LLM (pip install logosai[llm]): openai, anthropic, google-genai, langchain
Desktop Agent: macOS: Peekaboo + Accessibility · Ubuntu: xdotool, xclip, scrot
Full Stack: Node.js 18+, PostgreSQL 14+
| Repository | Description |
|---|---|
| logosai-ontology | Multi-agent orchestration (GNN+RL+KG+LLM) |
| logosai-api | FastAPI backend server |
| logosai-web | Next.js frontend |
| logosai-pulse | Agent Observability (traces, metrics, feedback) |
MIT — Copyright (c) 2023-2026 LogosAI