Overview

A Python framework for autonomous agent networks that handle task automation with multi-step reasoning.

Visit:

• Playground
• Documentation
• Github
• Python SDK

<hr />

Table of Content

<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

• Key Features
  • Agent Network
  • Graph Theory Concept
  • Task Graph
  • Optimization
• Quick Start
  • Package installation
  • Launching an agent
  • Automating workflows
  • Executing a single task
  • Supervising agents
• Technologies Used
• Project Structure
• Setting Up Your Project
  • Installing package manager
  • Installing dependencies
  • Adding env secrets to .env file
• Contributing
  • Steps
  • Package Management with uv
  • Pre-Commit Hooks
  • Documentation
• Trouble Shooting
• Frequently Asked Questions (FAQ)

<!-- END doctoc generated TOC please keep comment here to allow auto update --> <hr />

Key Features

versionhq is a Python framework designed for automating complex, multi-step tasks using autonomous agent networks.

Users can either configure their agents and network manually or allow the system to automatically manage the process based on provided task goals.

Agent Network

Agents adapt their formation based on task complexity.

You can specify a desired formation or allow the agents to determine it autonomously (default).

| | Solo Agent | Supervising | Squad | Random | | :--- | :--- | :--- | :--- | :--- | | Formation | <img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/rbgxttfoeqqis1ettlfz.png" alt="solo" width="200"> | <img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/zhungor3elxzer5dum10.png" alt="solo" width="200"> | <img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/dnusl7iy7kiwkxwlpmg8.png" alt="solo" width="200"> | <img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/sndpczatfzbrosxz9ama.png" alt="solo" width="200"> | | Usage | <ul><li>A single agent with tools, knowledge, and memory.</li><li>When self-learning mode is on - it will turn into Random formation.</li></ul> | <ul><li>Leader agent gives directions, while sharing its knowledge and memory.</li><li>Subordinates can be solo agents or networks.</li></ul> | <ul><li>Share tasks, knowledge, and memory among network members.</li></ul> | <ul><li>A single agent handles tasks, asking help from other agents without sharing its memory or knowledge.</li></ul> | | Use case | An email agent drafts promo message for the given audience. | The leader agent strategizes an outbound campaign plan and assigns components such as media mix or message creation to subordinate agents. | An email agent and social media agent share the product knowledge and deploy multi-channel outbound campaign. | 1. An email agent drafts promo message for the given audience, asking insights on tones from other email agents which oversee other clusters. 2. An agent calls the external agent to deploy the campaign. |

<hr />

Graph Theory Concept

To completely automate task workflows, agents will build a task-oriented network by generating nodes that represent tasks and connecting them with dependency-defining edges.

Each node is triggered by specific events and executed by an assigned agent once all dependencies are met.

While the network automatically reconfigures itself, you retain the ability to direct the agents using should_reform variable.

The following code snippet explicitly demonstrates the TaskGraph and its visualization, saving the diagram to the uploads directory.

import versionhq as vhq

task_graph = vhq.TaskGraph(directed=False, should_reform=True) # triggering auto formation

task_a = vhq.Task(description="Research Topic")
task_b = vhq.Task(description="Outline Post")
task_c = vhq.Task(description="Write First Draft")

node_a = task_graph.add_task(task=task_a)
node_b = task_graph.add_task(task=task_b)
node_c = task_graph.add_task(task=task_c)

task_graph.add_dependency(
   node_a.identifier, node_b.identifier,
   dependency_type=vhq.DependencyType.FINISH_TO_START, weight=5, description="B depends on A"
)
task_graph.add_dependency(
   node_a.identifier, node_c.identifier,
   dependency_type=vhq.DependencyType.FINISH_TO_FINISH, lag=1, required=False, weight=3
)

# To visualize the graph:
task_graph.visualize()

# To start executing nodes:
latest_output, outputs = task_graph.activate()

assert isinstance(last_task_output, vhq.TaskOutput)
assert [k in task_graph.nodes.keys() and v and isinstance(v, vhq.TaskOutput) for k, v in outputs.items()]

<hr />

Task Graph

A TaskGraph represents tasks as nodes and their execution dependencies as edges, automating rule-based execution.

Agent Networks can handle TaskGraph objects by optimizing their formations.

<img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1739337639/pj_m_home/zfg4ccw1m1ww1tpnb0pa.png" width="300px"> <hr />

Optimization

Autonomous agents are model-agnostic and can leverage their own and their peers' knowledge sources, memories, and tools.

Agents are optimized during network formation, but customization is possible before or after.

The following code snippet demonstrates agent customization:

import versionhq as vhq

agent = vhq.Agent(role="Marketing Analyst")

# update the agent
agent.update(
   llm="gemini-2.0", # updating LLM (Valid llm_config will be inherited to the new LLM.)
   tools=[vhq.Tool(func=lambda x: x)], # adding tools
   max_rpm=3,
   knowledge_sources=["<KC1>", "<KS2>"], # adding knowledge sources. This will trigger the storage creation.
   memory_config={"user_id": "0001"}, # adding memories
   dummy="I am dummy" # <- invalid field will be automatically ignored
)

<hr />

Quick Start

Package installation

pip install versionhq

(Python 3.11 | 3.12 | 3.13)

Launching an agent

import versionhq as vhq

agent = vhq.Agent(role="Marketer")
res = agent.start()

assert isinstance(res, vhq.TaskOutput) # contains agent's response in text, JSON, Pydantic formats with usage recordes and eval scores.

Automating workflows

import versionhq as vhq

network = vhq.form_agent_network(
   task="draft a promo plan",
   expected_outcome="marketing plan, budget, KPI targets",
)
res, tg = network.launch()

assert isinstance(res, vhq.TaskOutput) # the latest output from the workflow
assert isinstance(tg, vhq.TaskGraph) # contains task nodes and edges that connect the nodes with dep-met conditions

Executing a single task

You can simply build and execute a task using Task class.

import versionhq as vhq
from pydantic import BaseModel

class CustomOutput(BaseModel):
   test1: str
   test2: list[str]

def dummy_func(message: str, **kwargs) -> str:
   test1 = kwargs["test1"] if kwargs and "test1" in kwargs else ""
   test2 = kwargs["test2"] if kwargs and "test2" in kwargs else ""
   if test1 and test2:
      return f"""{message}: {test1}, {", ".join(test2)}"""

task = vhq.Task(
   description="Amazing task",
   response_schema=CustomOutput,
   callback=dummy_func,
   callback_kwargs=dict(message="Hi! Here is the result: ")
)

res = task.execute(context="testing a task function")
assert isinstance(res, vhq.TaskOutput)

Supervising agents

To create an agent network with one or more manager agents, designate members using the is_manager tag.

import versionhq as vhq

agent_a = vhq.Agent(role="Member", llm="gpt-4o")
agent_b = vhq.Agent(role="Leader", llm="gemini-2.0")

task_1 = vhq.Task(
   description="Analyze the client's business model.",
   response_schema=[vhq.ResponseField(title="test1", data_type=str, required=True),],
   allow_delegation=True
)

task_2 = vhq.Task(
   description="Define a cohort.",
   response_schema=[vhq.ResponseField(title="test1", data_type=int, required=True),],
   allow_delegation=False
)

network =vhq.AgentNetwork(
   members=[
      vhq.Member(agent=agent_a, is_manager=False, tasks=[task_1]),
      vhq.Member(agent=agent_b, is_manager=True, tasks=[task_2]), # Agent B as a manager
   ],
)
res, tg = network.launch()

assert isinstance(res, vhq.NetworkOutput)
assert not [item for item in task_1.processed_agents if "vhq-Delegated-Agent" == item]
assert [item for item in task_1.processed_agents if "agent b" == item]

This will return a list with dictionaries with keys defined in the ResponseField of each task.

Tasks can be delegated to a man