gnosari-engine 0.1.2

A powerful framework for orchestrating multi-agent teams using Large Language Models. Create intelligent AI agent swarms that collaborate through streaming delegation and dynamic tool discovery.

Gnosari AI Workforce

Gnosari AI Workforce is a powerful framework for orchestrating multi-agent teams using Large Language Models. Create intelligent AI agent swarms that collaborate through streaming delegation and dynamic tool discovery.

What is Gnosari AI Workforce?

Gnosari AI Workforce enables you to build sophisticated multi-agent systems where AI agents can:

• 🤝 Delegate tasks to specialized agents in real-time
• 🔧 Discover and use tools dynamically through MCP servers
• 📚 Query knowledge bases for context-aware responses
• 🌐 Make API calls to external services
• 🗄️ Query databases for data-driven decisions
• 📊 Stream responses for real-time collaboration

Key Features

Multi-Provider LLM Support

Each agent can use different models from various providers:

• OpenAI (GPT-4, GPT-4o, etc.)
• Anthropic (Claude)
• DeepSeek
• Google (Gemini)
• And more...

Task Delegation & Handoffs

Agents can both delegate tasks and transfer control with configurable instructions:

• Delegation: Use the delegate_agent tool to send tasks to other agents and get their responses
• Handoffs: Transfer control to other agents when they should take over the conversation
• Configurable Instructions: Specify exactly when and how agents should delegate or transfer control
• Auto-Tool Injection: The delegate_agent tool is automatically added when delegation is configured

Tool Integration

• Built-in tools (delegate_agent, api_request, knowledge_query, mysql_query, website_content, file_operations)
• MCP (Model Context Protocol) server integration
• Dynamic tool discovery

Knowledge Bases

Embedchain integration for RAG capabilities with support for:

• Websites
• YouTube videos
• Documents
• And more...

Quick Start

Prerequisites

• Python 3.12+ installed on your system
• Poetry for dependency management
• API Keys for the LLM providers you want to use

Installation

1. Clone the Repository

git clone https://github.com/neomanex/gnosari-engine.git
cd gnosari-engine

2. Install Dependencies

poetry install

3. Set Up Environment Variables Create a .env file in the project root:

# OpenAI (required for most examples)
OPENAI_API_KEY=your-openai-api-key

# Optional: Other providers
ANTHROPIC_API_KEY=your-anthropic-key
DEEPSEEK_API_KEY=your-deepseek-key

Your First Team

Create a file called my-first-team.yaml:

name: My First Team

# Define tools for the team
tools:
  - name: delegate_agent
    module: gnosari.tools.delegate_agent
    class: DelegateAgentTool
    args:
      pass

# Define agents
agents:
  - name: Coordinator
    instructions: >
      You are a helpful coordinator who manages tasks and delegates work to specialists.
      When you receive a request, analyze it and delegate to the appropriate specialist.
      Always provide a summary of the work completed.
    orchestrator: true
    model: gpt-4o
    tools:
      - delegate_agent

  - name: Writer
    instructions: >
      You are a professional writer who creates clear, engaging content.
      When given a writing task, focus on clarity, structure, and engaging the reader.
      Always ask for clarification if the requirements are unclear.
    model: gpt-4o

  - name: Researcher
    instructions: >
      You are a thorough researcher who gathers and analyzes information.
      When given a research task, provide comprehensive, well-sourced information.
      Always cite your sources and note any limitations in the information.
    model: gpt-4o

Run Your Team

# Run entire team
poetry run gnosari --config "my-first-team.yaml" --message "Write a blog post about the benefits of renewable energy"

# Run specific agent
poetry run gnosari --config "my-first-team.yaml" --message "Research renewable energy trends" --agent "Researcher"

# With streaming output
poetry run gnosari --config "my-first-team.yaml" --message "Your message" --stream

# With debug mode
poetry run gnosari --config "my-first-team.yaml" --message "Your message" --debug

Advanced Configuration

Delegation and Handoff Instructions

Configure specific delegation and handoff behavior with detailed instructions:

name: Advanced Coordination Team

# The delegate_agent tool is automatically added when delegation is configured
tools:
  - name: delegate_agent
    module: gnosari.tools.delegate_agent
    class: DelegateAgentTool
    args:
      pass

agents:
  - name: Coordinator
    instructions: >
      You are a coordinator who manages conversations and tasks with multiple specialized agents.
      You have two main mechanisms for working with other agents:
      1. DELEGATION: Use the delegate_agent tool to send tasks to other agents and get their responses
      2. HANDOFFS: Transfer control to other agents when they should take over the conversation
    orchestrator: true
    model: gpt-4o
    # Configure which agents to delegate to and when
    delegation:
      - agent: Alice
        instructions: Delegate to Alice for questions about fruits, especially apples, or when detailed fruit knowledge is needed
      - agent: Bob
        instructions: Delegate to Bob for general questions, math problems, or when Alice cannot help
    # Configure which agents to transfer control to and when
    can_transfer_to: 
      - agent: Alice
        instructions: Transfer to Alice when the user wants to have an ongoing conversation about fruits or gardening
      - agent: Bob
        instructions: Transfer to Bob for complex problem-solving sessions or when extended technical discussion is needed
    # Note: delegate_agent tool is automatically added due to delegation configuration
    # tools:
    #   - delegate_agent

  - name: Alice
    model: gpt-4o
    instructions: >
      You are Alice, a fruit specialist with deep knowledge about apples, orchards, and fruit cultivation.
      Provide detailed, accurate information about fruits and respond helpfully to questions in your domain.
    can_transfer_to:
      - agent: Bob
        instructions: Transfer to Bob if asked about topics outside fruit/gardening expertise
      - agent: Coordinator
        instructions: Transfer back to Coordinator when the conversation should be coordinated with multiple agents

  - name: Bob
    model: gpt-4o
    instructions: >
      You are Bob, a general-purpose assistant skilled in mathematics, problem-solving, and general knowledge.
      Provide clear, accurate responses and help with a wide range of topics.
    can_transfer_to:
      - agent: Alice
        instructions: Transfer to Alice for any fruit, apple, or gardening related questions
      - agent: Coordinator
        instructions: Transfer back to Coordinator when complex multi-agent coordination is needed

Team with Knowledge Bases and Tools

name: Advanced Content Team

# Knowledge bases (automatically adds knowledge_query tool)
knowledge:
  - name: "company_docs"
    type: "website"
    data: ["https://docs.yourcompany.com"]

# Tools configuration
tools:
  - name: delegate_agent
    module: gnosari.tools.delegate_agent
    class: DelegateAgentTool
    args:
      pass

  - name: api_request
    module: gnosari.tools.api_request
    class: APIRequestTool
    args:
      base_url: https://api.example.com
      base_headers:
        Authorization: Bearer ${API_TOKEN}
        Content-Type: application/json
      timeout: 30
      verify_ssl: true

  - name: mysql_query
    module: gnosari.tools.mysql_query
    class: MySQLQueryTool
    args:
      host: ${DB_HOST}
      port: 3306
      database: ${DB_NAME}
      username: ${DB_USER}
      password: ${DB_PASSWORD}
      pool_size: 5
      query_timeout: 30

# Agents configuration
agents:
  - name: Content Manager
    instructions: >
      You are a content manager who coordinates content creation workflows.
      You can delegate tasks to specialists and use various tools to gather information.
      Always ensure content is accurate, engaging, and meets quality standards.
    orchestrator: true
    model: gpt-4o
    tools:
      - delegate_agent
      - knowledge_query
    knowledge: ["company_docs"]

  - name: Data Analyst
    instructions: >
      You are a data analyst who works with databases and APIs to gather insights.
      Use the mysql_query tool to analyze data and the api_request tool to fetch external data.
      Always provide clear, actionable insights based on the data.
    model: gpt-4o
    tools:
      - mysql_query
      - api_request

  - name: Content Writer
    instructions: >
      You are a professional content writer who creates engaging, well-researched content.
      Use the knowledge_query tool to access company documentation and ensure accuracy.
      Focus on creating content that resonates with the target audience.
    model: gpt-4o
    tools:
      - knowledge_query
    knowledge: ["company_docs"]

Built-in Tools

Tool	Description	Use Case
delegate_agent	Delegate tasks to other agents in the team	Multi-agent coordination
api_request	Make HTTP requests to external APIs	External service integration
knowledge_query	Query knowledge bases for information	RAG and information retrieval
mysql_query	Execute SQL queries against MySQL databases	Database operations
website_content	Fetch content from websites via API	Web content retrieval
file_operations	Read, write, and manage files in a sandboxed directory	Local file management

Knowledge Base Support

Gnosari AI Workforce supports various knowledge sources through Embedchain:

• Websites: Crawl and index content from websites
• YouTube: Extract and index content from YouTube videos
• Documents: Process PDF, text, CSV, and JSON files
• Direct Text: Q&A content and structured information

CLI Options

# Basic team execution
poetry run gnosari --config "team.yaml" --message "Your message"

# Run specific agent from team
poetry run gnosari --config "team.yaml" --message "Your message" --agent "AgentName"

# With streaming output
poetry run gnosari --config "team.yaml" --message "Your message" --stream

# With debug mode
poetry run gnosari --config "team.yaml" --message "Your message" --debug

# With custom model and temperature
poetry run gnosari --config "team.yaml" --message "Your message" --model "gpt-4o" --temperature 0.7

# View generated system prompts (useful for debugging and understanding agent behavior)
poetry run gnosari --config "team.yaml" --show-prompts

# View prompts with specific model/temperature settings
poetry run gnosari --config "team.yaml" --show-prompts --model "gpt-4o" --temperature 0.5

Architecture

Core Components

• Team Builder: Builds teams from YAML configs using OpenAI Agents SDK with handoffs
• Team Runner: Executes team workflows using OpenAI Agents SDK Runner with streaming support
• Agent System: Uses OpenAI's official Agents SDK with native handoff support
• Tool Integration: Native OpenAI tool calling with MCP server integration
• Knowledge Bases: Embedchain integration for RAG capabilities

Key Directories

• src/gnosari/: Main source code
  • agents/: Agent implementations
  • engine/: Team orchestration and execution
  • tools/: Built-in tools (delegation, API requests, etc.)
  • prompts/: Prompt engineering utilities
  • schemas/: Pydantic schemas and base classes
  • utils/: LLM client, tool manager, knowledge manager
• examples/: Team configuration examples
• tests/: Test files
• docs/: Documentation

Development

Testing

# Run all tests
poetry run pytest

# Run specific test
poetry run pytest tests/test_specific.py

# Run tests with coverage
poetry run pytest --cov=gnosari

Alternative Execution

If experiencing pyenv shim issues, use the wrapper script:

./scripts/run-gnosari team run --config "examples/team.yaml" --message "Your message"

Documentation

For comprehensive documentation, visit the docs folder which includes:

• Quickstart Guide - Get up and running in minutes
• Agents - Learn about agent configuration and capabilities
• Teams - Understand team structure and coordination
• Orchestration - Learn about agent coordination and workflow management
• Knowledge Bases - Set up knowledge bases for RAG capabilities
• Tools Overview - Learn about built-in tools and how to use them

Contributing

We welcome contributions! Please see our contributing guidelines and feel free to submit issues and pull requests.

License

This project is licensed under the Creative Commons Attribution 4.0 International License - see the LICENSE file for details.

You are free to:

• Share and redistribute the code
• Modify and adapt the code
• Use the code for any purpose, including commercial purposes
• Use the code in commercial products or services

You must:

• Provide proper attribution when using the code
• Indicate any changes made
• Link to the license

---

Ready to build your first AI workforce? Start with the Quickstart Guide and create intelligent multi-agent teams that can tackle complex tasks through collaboration and specialization! 🚀