The Problem

Developers need a lightweight framework to assemble autonomous agents that can call LLMs, perform tool actions and keep short‑term / long‑term memory. Existing solutions are either heavyweight or undocumented, making rapid prototyping difficult.

What This Does

openagi provides a modular Python stack for building single‑ or multi‑agent pipelines. Core components live in src/openagi/:

  • Agent orchestration – src/openagi/agent.py defines Admin and the run loop (run).
  • Task planning – src/openagi/planner/task_decomposer.py implements TaskPlanner.plan.
  • LLM adapters – src/openagi/llms/*.py (e.g., openai.py, gemini.py) expose a common run interface.
  • Memory – src/openagi/memory/memory.py supplies vector‑store backed long‑term memory.
  • Actions / tools – each tool (e.g., src/openagi/actions/tools/ddg_search.py) inherits from BaseAction and implements execute.

The repository also ships dozens of ready‑made examples (example/*.py) and “cookbooks” that stitch these pieces together.

How It Is Wired

Execution begins at the CLI entry point src/openagi/cli.py → main(). The most common programmatic entry is the run function in src/openagi/agent.py (line 434). From there:

  1. run → calls 60 internal functions, most notably single_agent_execution which invokes the configured LLM via self.llm.run.
  2. LLM call – the LLM adapters (src/openagi/llms/*.py) forward to the external model service (OpenAI, Gemini, etc.). This is the only outbound model network call.
  3. Memory writes – src/openagi/memory/base.py → save_task and clear_long_term_memory interact with the vector store on the filesystem (no external DB).
  4. Tool actions – each action’s execute may perform I/O or network calls; e.g., github_search_tool.py makes an HTTP request via requests.get.
  5. Worker loop – src/openagi/worker.py::_force_output drives task iteration, calling run_action → execute → LLM again.

The internal call graph shows 173 resolved edges; the most‑referenced symbols are OpenAGIException (8 callers) and utility lower (5 callers). No circular import cycles were detected, so the dependency surface is shallow. The widest blast radius belongs to run (60 downstream functions) and OpenAGIException (multiple error‑handling paths).

How To Use It

# Clone the repo
git clone https://github.com/moses-y/openagi
cd openagi

# Install editable version
pip install -e .

Configuration

Set the LLM provider keys required by the adapters you plan to use, e.g.:

export OPENAI_API_KEY="sk-..."
export GEMINI_API_KEY="..."
export TAVILY_API_KEY="..."

These variables are read by the static load_from_env_config methods in each LLM module (src/openagi/llms/openai.py, gemini.py, etc.).

Running

For a quick test run the built‑in CLI:

python -m openagi.cli run "Summarize the latest AI news"

Or execute one of the examples, e.g.:

python example/blog_post.py

Both routes instantiate Admin (from src/openagi/agent.py), load the LLM, attach a Worker and invoke admin.run(...).

Real‑World Use

A product team could embed openagi as a microservice that receives a user query, creates a TaskPlanner, selects the appropriate tool set (search, retrieval, code generation), and returns a synthesized answer. The service would call admin.run() inside an HTTP handler, reusing the same memory store across requests to maintain context.

Code Health & Issues

  • High – Add a test suite – 82 source files, no tests.
  • Medium – Declare least‑privilege permissions for GITHUB_TOKEN – workflow .github/workflows/pr_review_check.yml lacks explicit permissions.
  • Medium – Enable Dependabot or Renovate – no automated dependency updates.
  • Medium – Gate pull requests on a dependency vulnerability scan – CI lacks a dependency‑review step.
  • Low – Set timeout‑minutes on workflow jobs – CI jobs have no timeout limits.

The static audit also flagged duplicated 6‑line code blocks across 25 files and deep nesting (max depth 11) in agent.py, memory/base.py, and tools/arxiv_search.py, which increase maintenance cost.

The Bottom Line

openagi delivers a clear, extensible Python framework for building LLM‑driven agents, with well‑separated components for planning, memory, and tooling. The codebase is functional but lacks automated tests and has several maintainability hot spots (duplication, deep nesting). It is suitable for teams comfortable adding their own test coverage and willing to refactor the shared helpers.