GenAgent Core

A generic autonomous AI agent framework with a two-tier architecture, CodeAct capabilities, and three-file planning mode.

Installation

pip install genagent-core

With optional dependencies (Sandbox & Memory):

pip install genagent-core[all]

Quick Start

import asyncio
from genagent_core import GenAgent, AgentConfig

async def main():
    # 1. Configure the agent
    config = AgentConfig(
        llm={
            "default_provider": "openai",
            "providers": {
                "openai": {
                    "base_url": "https://api.openai.com/v1",
                    "api_keys": ["sk-..."]
                }
            }
        },
        sandbox={
            "enabled": True,
            "provider": "e2b",
            "api_key": "e2b_..."
        }
    )
    
    # 2. Initialize the framework
    agent = GenAgent(config)
    
    # 3. Run a task
    task_state = await agent.run(
        instruction="Analyze the top 3 AI agent frameworks and generate a comparison report."
    )
    
    print(f"Task completed. Status: {task_state.status}")

if __name__ == "__main__":
    asyncio.run(main())

Core Features

1. Two-Tier Architecture: Planner Agent breaks down complex tasks into phases, while Executor Agents handle specific steps.
2. Three-File Planning Mode: Uses task_plan.md, findings.md, and progress.md for robust state management and seamless resume.
3. CodeAct (Executable Python as Actions): Executors use a stateful Jupyter Kernel (python_exec) for data analysis, visualization, and multi-step logic. Variables persist across cells, and generated charts are automatically saved as artifacts.
4. Seamless Resume: If the process crashes, the Orchestrator reads the sandbox files to resume exactly where it left off.
5. Smart Context Compression: Two-phase deterministic context management (Compact → Summarize) to prevent context window overflow during long-running tasks.
6. MCP Integration: Connect any MCP-compatible server (stdio, SSE, or HTTP streaming) and its tools are automatically registered and available to all Executor agents.
7. Skills System: Teach Executor agents domain-specific workflows via Markdown SKILL.md files — injected into the system prompt at task start.

Advanced Configuration

MCP Servers

Connect any Model Context Protocol server. Tools are automatically registered and available to all Executor agents.

Install the MCP dependency first:

pip install mcp httpx

from genagent_core import AgentConfig
from genagent_core.config import MCPServerConfig

config = AgentConfig(
    mcp_servers={
        # stdio: spawn a local subprocess
        "filesystem": MCPServerConfig(
            command="npx",
            args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
        ),
        # HTTP streaming: connect to a remote MCP server
        "my-api": MCPServerConfig(
            url="https://my-mcp-server.example.com/mcp",
            headers={"Authorization": "Bearer sk-..."},
            enabled_tools=["search", "fetch"],  # restrict to specific tools
            tool_timeout=60,
        ),
        # SSE: URL ending with /sse is auto-detected
        "sse-server": MCPServerConfig(
            url="https://my-mcp-server.example.com/sse",
        ),
    }
)

agent = GenAgent(config)
# MCP connections are established lazily on first agent.run() call
# and kept alive for the lifetime of the GenAgent instance.
# Call await agent.aclose() when done to cleanly shut down connections.

Transport auto-detection (when type is omitted):

Skills

Skills are Markdown files (SKILL.md) that teach Executor agents domain-specific workflows. They are injected into the system prompt at task start.

Directory layout:

skills/
  my-skill/
    SKILL.md        ← required
    scripts/        ← optional helper scripts
  another-skill/
    SKILL.md

SKILL.md frontmatter:

---
name: my-skill
description: Brief description shown in the skills index.
always: false      # set true to always inject full content
metadata: {"requires": {"bins": ["git"], "env": ["MY_API_KEY"]}}
---
# My Skill
...

Configuration:

from genagent_core import AgentConfig
from genagent_core.config import SkillsConfig

config = AgentConfig(
    skills=SkillsConfig(
        enabled=True,
        skills_dirs=["./skills"],        # directories to search for skills
        always_load=["coding-style"],    # always inject these skills in full
        inject_summary=True,             # inject <skills> XML index (default: True)
    )
)

Two-tier injection strategy:

The agent reads full skill content on demand via file_read when it needs the details. Skills with unmet requirements (bins/env) are listed as available="false" in the index.

Context Compression

You can configure the context compression thresholds similar to LangChain's memory management:

from genagent_core import AgentConfig
from genagent_core.config import ContextConfig

config = AgentConfig(
    context=ContextConfig(
        model_token_limit=128_000,
        compact_threshold=0.75,    # Phase 1: Truncate long tool results when context is 75% full
        summarize_threshold=0.90,  # Phase 2: Summarize old messages when context is 90% full
        max_tool_result_chars=3000 # Max characters to keep per tool result during Phase 1
    )
)

License

MIT