Plutus AI

0.3.240 · active · verified Thu Apr 16

Plutus AI is an autonomous AI agent framework designed for local execution, featuring subprocess orchestration, dynamic tool creation, and a local-first web interface. It allows users to define and run AI agents on their own machines, leveraging external LLMs. The current version is 0.3.240, and the library is in active development with frequent (often daily) releases.

Common errors

```
`plutus` command not found
```
cause The Plutus AI command-line interface (CLI) is not installed or its executable path is not in your system's PATH environment variable.

fix First, ensure `pip install plutus-ai` was successful. If so, verify that your Python environment's scripts directory is included in your system's PATH. On Linux/macOS, this is often `~/.local/bin`.
```
Agent 'MyAgentName' not found
```
cause When using `plutus run` or `plutus chat`, the specified agent name does not correspond to an agent definition known to the Plutus system.

fix Make sure you have correctly defined and saved the agent (e.g., via the Plutus web UI, a YAML file, or programmatically registered it if that functionality is available for your version). Double-check the agent name for typos.
```
No API key found for LLM provider / Missing required environment variable for LLM
```
cause The Plutus agent attempted to use an LLM (e.g., OpenAI, Anthropic) but could not find the corresponding API key in the environment variables.

fix Set the required API key as an environment variable (e.g., `export OPENAI_API_KEY='sk-...'`) in your terminal session before running Plutus, or add it to a `.env` file that Plutus can load.

Warnings

gotcha Plutus AI is currently in a pre-1.0 development phase (version 0.3.x). Expect frequent breaking changes to agent specifications, API interfaces, and core functionalities between minor versions.
Fix: Always review the latest GitHub README and example code when upgrading to a new minor version. Pin your `plutus-ai` dependency to a specific patch version (e.g., `plutus-ai==0.3.240`) in production environments.
gotcha The `Agent` and `Goal` classes are primarily for defining agent specifications and tasks. They do not have simple `.run()` methods for direct programmatic execution. Agent execution is typically managed via the `plutus` CLI or the local web interface.
Fix: To run an agent defined in Python, you often need to save its spec (e.g., to YAML) or pass it via CLI arguments, then invoke the `plutus` command (e.g., `plutus run --agent MyAgent --goal "Do something"`). Consider the library for definition and the CLI/UI for orchestration.
breaking Plutus AI requires Python 3.11 or higher. Running with older Python versions (e.g., 3.10 or 3.9) will result in installation failures or runtime errors due to syntax or dependency incompatibilities.
Fix: Upgrade your Python environment to version 3.11 or 3.12. Using a tool like `pyenv` or `conda` can help manage multiple Python versions.
gotcha Plutus AI relies on external Large Language Models (LLMs) and requires appropriate API keys to be configured as environment variables (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`). Without these, agents will fail to interact with LLMs.
Fix: Ensure the necessary LLM API key environment variables are set in your shell or `.env` file before launching Plutus. Refer to the specific LLM provider's documentation for required keys.

Install

pip install plutus-ai Install Plutus AI

Imports

Agent
```
from plutus import Agent
```
Goal
```
from plutus import Goal
```

Quickstart

This quickstart demonstrates how to programmatically define an Agent and a Goal object using the Plutus AI library. It highlights the primary use of these classes for defining agent behaviors and tasks. To execute agents, the Plutus CLI (`plutus run` or `plutus chat`) or the local web UI is typically used, as the `Agent` class itself is a definition rather than an executor.

from plutus import Agent, Goal
import os # Good practice for potential environment variables

# Define an agent specification as a dictionary
agent_spec = {
    "name": "SimpleGreeterBot",
    "instructions": "You are a friendly bot that greets the user and introduces yourself.",
    "goals": ["Greet the user, introduce yourself, and then finish the conversation."],
    "tools": [],
}

# Instantiate the Agent and Goal definitions from the plutus library
agent = Agent(spec=agent_spec)
goal = Goal(description="Say hello to the user and finish the task.")

print(f"Successfully defined Agent: '{agent.name}'")
print(f"Instructions: '{agent.instructions}'")
print(f"Goal: '{goal.description}'")

# Note: To *run* this agent, you typically use the Plutus CLI, for example:
# 1. Ensure the agent spec is accessible (e.g., saved via Plutus UI or a YAML file).
# 2. Run from your terminal: `plutus chat --agent SimpleGreeterBot --goal "Say hello!"`
#    Or `plutus run --agent SimpleGreeterBot --goal "Say hello!"`

view raw JSON →