A Python framework for autonomous agent networks that handle task automation with multi-step reasoning.
Visit:
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.
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 |  |
 |
 |
 |
| Usage |
|
|
|
|
| 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. |
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 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,
type=vhq.DependencyType.FINISH_TO_START, weight=5, description="B depends on A"
)
task_graph.add_dependency(
node_a.identifier, node_c.identifier,
type=vhq.DependencyType.FINISH_TO_FINISH, lag=1, required=False, weight=3
)
task_graph.visualize()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.
The following example demonstrates a simple concept of a supervising agent network handling a task graph with three tasks and one critical edge.
pip install versionhq
(Python 3.11 / 3.12)
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.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 conditionsYou 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, test1: str, test2: list[str]) -> str:
return f"""{message}: {test1}, {", ".join(test2)}"""
task = vhq.Task(
description="Amazing task",
pydantic_output=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)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_fields=[vhq.ResponseField(title="test1", data_type=str, required=True),],
allow_delegation=True
)
task_2 = vhq.Task(
description="Define a cohort.",
response_fields=[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 manager, peers within the agent network, or a completely new agent.
| LLM Orchestration Framework | Core | Analyics | Use Case | |
|---|---|---|---|---|
| Github | repo_a | repo_b | repo_c | repo_d |
| Website | PyPI | - | - | client app |