{"id":25452608,"url":"https://github.com/corzed/orchestrai","last_synced_at":"2026-03-07T06:32:36.506Z","repository":{"id":276042109,"uuid":"928023140","full_name":"Corzed/OrchestrAI","owner":"Corzed","description":"a powerful framework for orchestrating collaborative AI agents. ","archived":false,"fork":false,"pushed_at":"2025-05-15T16:48:18.000Z","size":135,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-16T12:14:44.200Z","etag":null,"topics":["agent","agentic","agents","ai","collaboration","communication","multi-agent","orchestration","tools"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Corzed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-05T23:39:27.000Z","updated_at":"2025-05-15T16:48:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"d623af4c-0fb8-47a1-8ec3-29f28e586a0b","html_url":"https://github.com/Corzed/OrchestrAI","commit_stats":null,"previous_names":["corzed/orchestrai"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Corzed/OrchestrAI","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Corzed%2FOrchestrAI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Corzed%2FOrchestrAI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Corzed%2FOrchestrAI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Corzed%2FOrchestrAI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Corzed","download_url":"https://codeload.github.com/Corzed/OrchestrAI/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Corzed%2FOrchestrAI/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30209087,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T05:23:27.321Z","status":"ssl_error","status_checked_at":"2026-03-07T05:00:17.256Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agentic","agents","ai","collaboration","communication","multi-agent","orchestration","tools"],"created_at":"2025-02-17T23:12:38.080Z","updated_at":"2026-03-07T06:32:36.477Z","avatar_url":"https://github.com/Corzed.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎭 OrchestrAI\n\n[![GitHub License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)\n\n**OrchestrAI** is a powerful framework for orchestrating collaborative AI agents. Build sophisticated multi-agent systems where specialized agents work together, use tools, and solve complex problems through coordinated actions.\n\n## 🔍 Overview\n\nOrchestrAI enables you to create and manage a network of AI agents that can:\n- Communicate and collaborate with each other\n- Use specialized tools with structured inputs and outputs  \n- Delegate tasks based on agent specialization\n- Follow a hierarchical or peer-to-peer organization\n- Execute complex workflows through agent coordination\n\n## ✨ Key Features\n\n- **Hierarchical Agent Architecture**: Create **parent-child** agent relationships with clear delegation paths\n- **Dynamic Tool Integration**: Define and attach tools to agents with proper parameter validation\n- **Structured Communication**: Agents communicate via a well-defined JSON schema for reliable interaction\n- **Flexible Deployment**: Use different models for different agents based on task complexity\n- **Comprehensive Logging**: Rich console output for debugging and monitoring agent activities\n- **Error Resilience**: Robust error handling for API calls, tool execution, and inter-agent communication\n\n## 📦 Installation\n\n```bash\n# Install from GitHub\npip install git+https://github.com/Corzed/OrchestrAI.git\n\n# Alternative: Clone and install locally\ngit clone https://github.com/Corzed/OrchestrAI.git\ncd OrchestrAI\npip install -e .\n```\n\n## 🚀 Quick Start\n\n### Basic Example: Single Agent with Tool\n\n```python\nfrom OrchestrAI import AgentManager, Agent, AgentTool\nimport os\n\n# Set up your OpenAI API key (or use .env file)\nos.environ[\"OPENAI_API_KEY\"] = \"your-api-key\"\n\n# Create an agent manager\nmanager = AgentManager()\n\n# Define a calculator tool\ndef calculator(a: str, b: str, operator: str) -\u003e str:\n    try:\n        a, b = int(a), int(b)\n        if operator == \"+\": return str(a + b)\n        elif operator == \"-\": return str(a - b)\n        elif operator == \"*\": return str(a * b)\n        elif operator == \"/\": \n            return str(a / b) if b != 0 else \"Error: Division by zero\"\n        else:\n            return f\"Error: Unsupported operator '{operator}'\"\n    except Exception as e:\n        return f\"Error: {e}\"\n\n# Create a tool object\ncalc_tool = AgentTool(\n    name=\"calculator\",\n    description=\"Performs basic arithmetic operations on two numbers\",\n    func=calculator\n)\n\n# Create an agent with the calculator tool\nmath_agent = Agent(\n    name=\"Math_Assistant\",\n    role=\"You are a helpful math assistant that can perform calculations\",\n    description=\"Performs mathematical calculations\",\n    manager=manager,\n    tools={\"calculator\": calc_tool},\n    verbose=True,\n    model=\"gpt-4o\" # Or any model you prefer\n)\n\n# Run a conversation with the agent\nresponse = math_agent.run_conversation(\"What is 125 * 37?\")\nprint(f\"Final answer: {response}\")\n```\n\n### Advanced Example: Multi-Agent Collaboration\n\n```python\nfrom OrchestrAI import AgentManager, Agent, AgentTool\n\n# Create manager\nmanager = AgentManager()\n\n# Create main orchestrator agent\norchestrator = Agent(\n    name=\"Orchestrator\",\n    role=\"You coordinate specialized agents to solve complex problems\",\n    description=\"Coordinates specialized agents\",\n    manager=manager,\n    verbose=True,\n    model=\"gpt-4o\"\n)\n\n# Create specialized math agent\nmath_agent = Agent(\n    name=\"Mathematician\",\n    role=\"You solve complex mathematical problems\",\n    description=\"Expert at mathematics\",\n    manager=manager,\n    tools={\"calculator\": calc_tool},  # Using the calc_tool from earlier\n    parent=orchestrator,  # Set parent relationship\n    verbose=True,\n    model=\"gpt-4o-mini\"  # Can use a smaller model for specialized tasks\n)\n\n# Create specialized writer agent\nwriter_agent = Agent(\n    name=\"Writer\",\n    role=\"You write clear explanations of complex topics\",\n    description=\"Expert at communication\",\n    manager=manager,\n    parent=orchestrator,  # Set parent relationship\n    verbose=True,\n    model=\"gpt-4o-mini\"\n)\n\n# Run a conversation that requires cooperation\nresponse = orchestrator.run_conversation(\n    \"Calculate the compound interest on $10,000 invested for 5 years at 8% APR, \"\n    \"and explain the result in simple terms for a non-financial person.\"\n)\nprint(f\"Final response: {response}\")\n```\n\n## 📋 Core Components\n\n### `AgentManager`\n\nThe central registry for all agents in your system:\n\n```python\nmanager = AgentManager()\nmanager.register(agent)  # Usually handled automatically\nagent = manager.get(\"agent_name\")\nmanager.unregister(\"agent_name\")\nall_agents = manager.all_agents()\n```\n\n### `Agent`\n\nThe primary actor in OrchestrAI:\n\n```python\nagent = Agent(\n    name=\"unique_name\",          # Required: Unique identifier\n    role=\"agent_instructions\",   # Required: Instructions for the AI\n    description=\"agent_summary\", # Required: Short description\n    manager=manager,             # Required: AgentManager\n    tools={},                    # Optional: Dictionary of AgentTools\n    parent=None,                 # Optional: Parent agent\n    verbose=False,               # Optional: Enable detailed logging\n    model=\"gpt-4o\",              # Optional: OpenAI model to use\n    api_key=None                 # Optional: API key (defaults to env)\n)\n```\n\n### `AgentTool`\n\nFunction with metadata that agents can call:\n\n```python\ntool = AgentTool(\n    name=\"tool_name\",           # Required: Name for the tool\n    description=\"tool_summary\", # Required: Description of what the tool does\n    func=my_function            # Required: The function to execute\n)\n```\n\nTool functions should have well-defined parameters and return strings for best results:\n\n```python\ndef my_tool(param1: str, param2: str) -\u003e str:\n    # Process inputs and return a string result\n    return f\"Processed {param1} and {param2}\"\n```\n\n## 🔄 Conversation Flow\n\n1. **User Input**: Start with `agent.run_conversation(user_message)`\n2. **Agent Processing**:\n   - Agent receives the message\n   - Agent decides on actions based on the message\n   - Agent may call tools or delegate to other agents\n3. **Final Response**: When ready, agent returns a final response\n\n## 🛠️ Advanced Usage\n\n### Custom System Messages\n\nTailor agent behaviors with custom system messages:\n\n```python\nagent.history.update_system(\n    \"You are a financial expert specializing in cryptocurrency market analysis. \"\n    \"Always explain your reasoning and cite sources.\"\n)\n```\n\n### Conversation History\n\nAccess and manipulate conversation history:\n\n```python\n# Add a system message\nagent.history.add_system(\"New system instructions\")\n\n# Add a user message\nagent.history.add_user(\"User input\")\n\n# Add an assistant message\nagent.history.add_assistant(\"Assistant response\")\n\n# Get all messages\nmessages = agent.history.get_messages()\n```\n\n### Error Handling\n\nOrchestrAI provides detailed error handling for various scenarios:\n\n```python\ntry:\n    response = agent.run_conversation(\"Complex query\")\n    print(f\"Success: {response}\")\nexcept Exception as e:\n    print(f\"Error: {e}\")\n    # You can inspect agent.history for debugging\n```\n\n## 📚 Examples\n\n### Research Assistant\n\n```python\n# Web search tool\ndef web_search(query: str) -\u003e str:\n    # Implement web search functionality here\n    return f\"Results for: {query}\"\n\nsearch_tool = AgentTool(\"web_search\", \"Search the web\", web_search)\n\n# Create research agent\nresearcher = Agent(\n    name=\"Researcher\",\n    role=\"You are a research assistant who finds information\",\n    description=\"Conducts research on topics\",\n    manager=manager,\n    tools={\"web_search\": search_tool},\n    model=\"gpt-4o\"\n)\n\n# Run a research task\nresponse = researcher.run_conversation(\"Find information about quantum computing\")\n```\n\n### Customer Support System\n\n```python\n# Create a multi-agent customer support system\nsupport_manager = Agent(\n    name=\"SupportManager\",\n    role=\"You manage customer support requests and delegate to specialists\",\n    description=\"Support request coordinator\",\n    manager=manager,\n    model=\"gpt-4o\"\n)\n\ntech_agent = Agent(\n    name=\"TechSupport\",\n    role=\"You solve technical problems with products\",\n    description=\"Technical specialist\",\n    parent=support_manager,\n    manager=manager,\n    model=\"gpt-4o-mini\"\n)\n\nbilling_agent = Agent(\n    name=\"BillingSupport\",\n    role=\"You handle billing and payment issues\",\n    description=\"Billing specialist\",\n    parent=support_manager,\n    manager=manager,\n    model=\"gpt-4o-mini\"\n)\n\n# Process a support request\nresponse = support_manager.run_conversation(\n    \"I'm having trouble connecting my device to Wi-Fi and I also need to update my payment method\"\n)\n```\n\n## 🔧 Debugging Tips\n\n- Use `verbose=True` to enable detailed console logging\n- Inspect `agent.history.get_messages()` to view the full conversation\n- Use `AgentTool` return values for debugging tool execution\n- Add intermediate `log_message()` calls in complex tool functions\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorzed%2Forchestrai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcorzed%2Forchestrai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorzed%2Forchestrai/lists"}