---
tags:
  - ai-agents
  - orchestration
  - python
  - cli
  - local-ai
license: mit
---

# Aegis

Aegis is a modular Python framework for composing controlled agent workflows, registries, memory, tool execution, policies, and evaluation.

The project currently provides a runnable command-line interface that executes tasks through the built-in Aegis orchestration layer.

## Current capabilities

- Typed agent and tool registries
- Planner, task agent, and evaluator workflow
- Runtime orchestration layer
- User-facing `aegis run` CLI
- Human-readable and structured JSON output
- Agent and workflow selection
- Execution step limits
- Stable process exit codes
- Pydantic-based contracts
- Ruff, mypy, and pytest validation
- Deterministic evaluation of task results

## Installation

### Clone from Hugging Face

This repository is currently private. You must authenticate with Hugging Face before cloning it.

```bash
hf auth login

git clone https://huggingface.co/jayc1978/aegis
cd aegis

python -m venv .venv
source .venv/bin/activate

pip install -e ".[dev]"
```

Verify the installation:

```bash
aegis run --help
aegis run "Run the default Aegis workflow"
```

## CLI usage

Run the default workflow:

```bash
aegis run "Review this repository"
```

Run a specific agent:

```bash
aegis run --agent default-task "Review this repository"
```

Return structured JSON:

```bash
aegis run --output json "Review this repository"
```

Limit execution steps:

```bash
aegis run --max-steps 10 "Review this repository"
```

## Development

Run the full validation suite:

```bash
pytest
ruff check .
mypy src
```

Current verified baseline:

- 56 tests passed
- Ruff passed
- mypy passed

## Current limitations

- Memory is currently in-process only.
- No Ollama or Hugging Face inference provider is connected yet.
- The default workflow is deterministic.
- Tool integrations and policy enforcement remain limited.
- No persistent database, API server, or web interface is included yet.

## Project direction

Aegis is intended to become an auditable, policy-controlled runtime for AI-agent automation.

Its purpose is to control:

- which tools an agent may use
- what data an agent may access
- when human approval is required
- how agent actions are evaluated
- how execution history is recorded

## License

This project is licensed under the MIT License. See `LICENSE` for details.