AgentCrewKit

Build AI teams, not just AI prompts.

AgentCrewKit is a lightweight Python starter kit for developers who want to understand, modify, and ship small multi-agent AI workflows without adopting a large framework. It plans a user goal, runs YAML-configured agents in dependency order, and reviews the result. The default crew requires a human decision before completion.

Install it, configure Ollama or OpenAI, then run a crew from the terminal:

agentcrew run "Research AI agents and create a report"

The runtime is synchronous and intentionally small. SQLite records run history, and no agent receives shell or filesystem access by default.

Features

• LLM-based planner with strict JSON validation, one repair attempt, and a configuration-driven fallback plan
• YAML-configured planner, researcher, writer, reviewer, and custom agents
• Provider-neutral runtime with OpenAI and Ollama HTTP adapters
• Stable dependency ordering and per-task output tracking
• LLM reviewer with structured scores, feedback, and required actions
• Bounded machine and human revision loop
• Human Approve, Reject, or Request Revision gate, enabled by default
• Agent-specific tool allowlists and a safe registration boundary
• Optional Tavily web search with an honest no-key fallback
• Run-scoped SQLite memory without a vector database
• Installable agentcrew CLI and an offline pytest suite

Architecture

User Goal
    |
    v
Planner (LLM + validated JSON)
    |
    v
Dependency-aware Task Plan
    |
    v
Orchestrator -> Selected Agent -> Task Output
    |                              |
    +------------------------------+
    |
    v
Reviewer (LLM + validated JSON)
    |
    +-- needs_revision --> Required Actions --> Relevant Agents
    |                                           |
    |                       Final Agent <--------+
    |                           |
    +---------------------------+
    |
    v
Human Approval: Approve / Reject / Request Revision
    |
    v
Final Output

The planner chooses only execution agents. Review and approval are control steps owned by the orchestrator, so a generated plan cannot bypass them.

Quick Start

Python 3.11 or newer is required. The default crew uses a local Ollama model, so install Ollama first and start its server in one terminal:

ollama serve

If Ollama Desktop is already running, the server is already available. In a second terminal:

git clone https://github.com/PromptLabStudio/agentcrewkit.git
cd agentcrewkit
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
cp .env.example .env
ollama pull qwen3
agentcrew run "Research AI agents and create a report"

On Windows PowerShell, use .venv\Scripts\Activate.ps1 and Copy-Item .env.example .env.

Useful commands:

agentcrew --help
agentcrew agents
agentcrew config
agentcrew version

Example CLI Output

An abridged run with one reviewer-requested revision looks like this:

AgentCrewKit
Build AI teams, not just AI prompts.

Goal
Research AI agents and create a report

[>] Planner
  Creating a task plan.

[OK] Planner
  Created 2 task(s).

[>] Researcher
  Research recent AI agent developments and preserve source URLs.

[OK] Researcher
  Task completed.

[>] Writer
  Create a concise report from the research.

[OK] Writer
  Task completed.

[>] Reviewer
  Reviewing candidate (iteration 1).

[REVISE] Reviewer
  Revision requested with score 0.72.

[>] Researcher
  Find evidence for the unsupported claim.

[OK] Researcher
  Revision support completed.

[>] Writer
  Integrating the revised final output.

[OK] Writer
  Final output revised.

[>] Reviewer
  Reviewing candidate (iteration 2).

[OK] Reviewer
  Approved candidate with score 0.91.

Candidate Output

# AI Agent Developments
...

Human Approval Required

[A] Approve
[R] Reject
[E] Request Revision
Choice: A

[OK] Human approved the final output.

Configuration

The default crew is in config/agents.yaml. Pass another file with --config:

agentcrew run "Create a launch brief" --config examples/content_team/agents.yaml

Minimal schema:

version: 1

provider:
  name: ollama
  model: qwen3
  base_url: http://localhost:11434
  timeout: 120

workflow:
  planner_agent: planner
  reviewer_agent: reviewer
  fallback_agent: writer
  max_iterations: 3
  max_tool_rounds: 1
  require_human_approval: true
  memory_path: .agentcrew/runs.db

agents:
  planner:
    role: Planning Specialist
    goal: Break goals into executable tasks
    instructions: Return a small dependency-aware plan.
    tools: []

  researcher:
    role: Research Specialist
    goal: Find reliable and relevant information
    instructions: State limitations and preserve source URLs.
    tools: [web_search]

  writer:
    role: Technical Writer
    goal: Turn research into structured content
    tools: []

  reviewer:
    role: Quality Reviewer
    goal: Evaluate accuracy, completeness, and clarity
    tools: []

Configuration is strict: unknown fields, duplicate YAML keys, invalid agent references, duplicate tools, and unsafe YAML tags fail with a clear error. fallback_agent is the execution agent that synthesizes the final result only when the planner fails both its initial JSON response and repair attempt.

Precedence for provider defaults is:

process environment > .env > provider section in YAML

Per-agent provider, model, and temperature values are explicit overrides for that agent.

Creating Agents

Add an entry under agents. The key is the name that the planner and reviewer use in structured output.

agents:
  fact_checker:
    role: Fact Checker
    goal: Find unsupported or contradictory claims
    instructions: Return concrete corrections with source references.
    provider: openai       # optional
    model: your-model      # optional
    temperature: 0.1       # optional
    tools:
      - web_search

Roles, goals, instructions, allowed tools, provider, and model are read from configuration. The Python runtime does not hardcode worker roles.

Providers

Ollama

AI_PROVIDER=ollama
AI_MODEL=qwen3
OLLAMA_BASE_URL=http://localhost:11434

Start Ollama separately with ollama serve. AgentCrewKit sends non-streaming requests to /api/chat and asks Ollama for JSON mode when the planner or reviewer needs structured output.

OpenAI

AI_PROVIDER=openai
AI_MODEL=your-model
OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://api.openai.com/v1

The OpenAI adapter uses the Chat Completions endpoint. The CLI and provider factory read API keys from environment variables; embedding applications may also pass a key directly to OpenAIProvider. AgentCrewKit does not write keys to YAML, prompts, memory, or logs.

The orchestration layer depends only on LLMProvider.generate(messages, ...). v0.1.0 configuration accepts only openai and ollama. Adding another provider requires implementing the interface, adding its name to configuration validation, and extending providers/factory.py; provider-specific logic should not be added to agents or the orchestrator.

Tools

ToolRegistry is an allowlist, not a sandbox. A tool must be registered in trusted Python code and named in an agent's YAML tools list before that agent can invoke it.

The CLI loads only the built-in registry. Embedding applications can pass a custom registry to the orchestrator:

from agentcrew import Orchestrator
from agentcrew.core.approval import ConsoleApproval
from agentcrew.tools import build_default_registry

registry = build_default_registry()
registry.register(
    "lookup_document",
    lookup_document,
    description="Read one document from an approved document store.",
    parameters={
        "type": "object",
        "properties": {"document_id": {"type": "string"}},
        "required": ["document_id"],
        "additionalProperties": False,
    },
)

# Add lookup_document to the relevant agent's YAML tools list as well.
orchestrator = Orchestrator.from_config("config/agents.yaml", tools=registry)
try:
    result = orchestrator.run(
        "Summarize the approved document",
        approval_handler=ConsoleApproval(),
    )
finally:
    orchestrator.close()

v0.1.0 ships only web_search. It calls Tavily when TAVILY_API_KEY is set; otherwise it returns status: unavailable and no results. There is no generic HTTP, shell, Python evaluation, or filesystem tool.

Human Approval

When require_human_approval is true (the default), reviewer approval does not finish an interactive run. While revision capacity remains, the CLI shows the candidate and asks:

Human Approval Required

[A] Approve
[R] Reject
[E] Request Revision

E asks for feedback, sends that feedback to the final agent, runs the LLM reviewer again, and asks for human approval again if the revised result passes. All review passes, including those after human feedback, count toward max_iterations. On the last permitted review, only approve and reject remain available. EOF and interrupted approval prompts fail closed as rejection.

Library users must pass an ApprovalHandler when human approval is enabled; there is no core auto-approval handler.

Memory

Each run stores the goal, plan, task outputs, revision outputs, reviewer decisions, and human decisions in SQLite. Retrieval is scoped to one run, so content does not leak into another run's prompt. Set workflow.memory_path or pass CLI --memory to choose the database path.

SQLite files contain plaintext model input and output. Protect or delete them when goals contain sensitive information. v0.1.0 records runs but does not resume interrupted workflows or perform cross-run semantic retrieval.

Examples

• examples/research_team: planner, researcher, writer, reviewer
• examples/content_team: planner, researcher, writer, SEO, reviewer
• examples/coding_team: planner, repository analyst, coder, tester, reviewer

These examples are configuration files, not privileged automation. In particular, the coding team cannot inspect or change a repository unless an embedding application supplies a narrowly scoped, approved tool.

Docker

The Compose file runs AgentCrewKit and Ollama as separate services:

docker compose up -d ollama
docker compose exec ollama ollama pull qwen3
docker compose run --rm agentcrew run \
  "Research AI agents and create a concise report" --memory /data/runs.db

Testing

python -m pip install -e ".[dev]"
ruff check .
pytest
python -m build

Tests use scripted providers and mocked HTTP boundaries. They require no API key and make no live provider requests. GitHub Actions runs the suite on Python 3.11 and 3.12.

Security

• Model, task, memory, and tool output are treated as untrusted text.
• Agent tool access is immutable for a run and limited by YAML plus the trusted registry.
• Tool arguments and output sizes are bounded.
• No arbitrary shell command, dynamic import, or unrestricted filesystem access is included.
• Human approval is a decision gate, not a sandbox for unsafe tools.
• .env, local databases, virtual environments, and build artifacts are ignored by Git.

Review every custom tool before registration. Side-effecting tools need their own permission, preview, and approval boundary. See SECURITY.md for supported versions and private vulnerability reporting.

Roadmap

Possible v0.2 work, not included in v0.1.0:

• Streaming progress and provider responses
• Editable plan approval before task execution
• Native provider tool-call adapters behind the existing registry
• Optional workflow resume from SQLite
• More granular tool permissions and side-effect previews
• Evaluation fixtures for comparing crew configurations

Not planned as default architecture: a vector database, arbitrary code execution, dynamic YAML plugins, or an enterprise workflow engine.

Contributing

Read CONTRIBUTING.md before submitting a change. Focused bug fixes, provider adapter improvements, safer tools, tests, and clear examples are welcome. Release notes are in CHANGELOG.md.

License

AgentCrewKit is released under the MIT License.