Agent A2As - Advanced Agentic Framework

Agent A2As is a high-performance, modular, and extensible AI agentic framework designed for complex, autonomous task execution. Built upon a robust hook-based architecture, it allows for seamless integration of specialized agents, custom tools, and experimental AI behaviors.

---

✨ Feature Highlights

• 🤖 Multi-Agent Orchestration: Hierarchical superior/subordinate delegation models for complex problem-solving.
• 🧩 Deep Extensibility: A unique @extensible hook system that allows for non-invasive logic injection at runtime.
• 🛠 MCP Support: Full integration with the Model Context Protocol (MCP) for nearly infinite capability expansion.
• 🌐 Robust Web UI: A specialized interactive dashboard with real-time reasoning and response streaming.
• 🕒 Task Scheduler: Built-in cron-like system for automating background agent tasks.
• 🚇 Secure Tunneling: Integrated support for exposing local agent APIs via secure tunnels (Cloudflare, etc).
• 📦 Self-Updating: Keep your framework, tools, and agents fresh with automated update paths.
• 📚 Localized Assets: Zero reliance on external CDNs; optimized for performance via mirrored vendor assets.

---

🧰 Powerful Toolbox

Agent A2As comes equipped with a suite of sophisticated tools enabling it to interact with the physical and digital world:

• 🔍 Document Intelligence: Query and analyze complex documents with the document_query tool.
• 🌐 Full-Featured Browser: Navigate the web, interact with pages, and extract data using integrated browser tools.
• 🖼️ Vision Capabilities: Process and understand visual information with vision_load.
• 🤝 Subordinate Delegation: Scalable task management via call_subordinate, allowing agents to spawn specialists.
• 📡 Agent-to-Agent (A2A): Collaborative multi-agent communication via the a2a_chat protocol.
• 🗓️ Background Scheduler: Defer and automate actions over time with the scheduler.

---

🏗 End-to-End Architecture

Agent A2As follows a multi-layered architecture where logic is decoupled from the user interface and the underlying language models.

graph TD
    UI[Web UI / API Clients] <--> API[Modular API Backend]
    API <--> AC[AgentContext]
    
    subgraph Core Engine
        AC --> A0[Agent 0 - Primary Orchestrator]
        A0 --> ML[Monologue Loop]
        ML --> P[Prompt Builder]
        ML --> LLM[Chat / Utility Models]
        ML --> T[Tool Execution Engine]
        T --> TS[Tools / Skills / MCP]
    end
    
    subgraph Extensibility Layer
        E[Extension Hooks] -.-> ML
        E -.-> P
        E -.-> T
        E -.-> A0
    end
    
    subgraph Multi-Agent Layer
        A0 <--> SA[Subordinate Agents]
        SA --> R[Researcher]
        SA --> D[Developer]
        SA --> H[Hacker]
    end

Loading

1. Orchestration Layer (AgentContext)

The AgentContext is the lifecycle manager for a session. It maintains the state of the conversation, handles background tasks, and manages the primary agent (Agent0).

• Context Management: Multi-context support allows running several independent tasks simultaneously.
• Process Chains: Handles the hierarchical delegation between "Superior" and "Subordinate" agents.

2. Core Engine (Agent)

The Agent class is the "brain" that executes the Monologue Loop. It transforms user intentions into actions.

• Thought Process: Implements reasoning and planning before taking actions.
• History Management: Sophisticated tracking of conversation history, tool results, and system instructions.
• Prompt Engineering: Dynamic prompt generation that incorporates real-time context and "extras."

3. Extensibility Framework (extensions)

The framework is built around Implicit Extension Points. Using the @extensible decorator, almost any function in the system can be hooked into (start/end) without modifying the source code.

• Plugin-like System: Add new features by placing Python scripts in specialized folders.
• Customizable Pipelines: Modify prompts, filter outputs, or intercept tool calls on the fly.

---

🔄 End-to-End Flow (The Monologue Loop)

When a user sends a message, Agent A2As enters a recursive execution cycle known as the Monologue Loop:

1. Ingestion: User input is wrapped in a UserMessage and passed to AgentContext.communicate().
2. Initialization: The monologue loop begins. Extension hooks like message_loop_start are triggered.
3. Prompt Building:
   • The system identifies the current agent's personality and configuration.
   • It compiles the system prompt, conversation history, and any transient "extras" (temporary context).
   • Tokens are calculated to ensure context window limits are respected.
4. LLM Call:
   • The LLM is invoked with the compiled prompt.
   • Reasoning: If supported, the agent's internal reasoning is streamed separately.
   • Response: The agent's final output or tool request is streamed.
5. Tool Execution:
   • The framework parses the response for tool calls (typicA2A JSON).
   • It validates the tool request against available skills/tools/MCP servers.
   • The tool is executed (e.g., running code, searching the web, modifying files).
6. Resolution:
   • Tool output is formatted and added back to the history.
   • If the agent has fulfilled the task, it provides a final response to the user.
   • If more work is needed, the loop repeats from Step 3.
7. Final Delivery: The final response is delivered to the UI, and the context waits for the next user input.

---

📁 System Structure

• /agents: Specialized agent profiles (Developer, Researcher, Hacker).
• /api: ASGI backend handlers for real-time interaction.
• /extensions: Backend logic hooks for lifecycle events.
• /skills: Modular Python skillsets for high-level capabilities.
• /tools: System-level integration drivers.
• /webui: Optimized frontend dashboard and component system.
• agent.py: Principal framework orchestrator and monologue implementation.
• run_ui.py: Primary server entry point.

---

🚀 Getting Started

1. Installation:

   pip install -r requirements.txt

2. Environment Setup: Copy .env.example to .env and configure your API keys (OpenAI, Anthropic, etc.).
3. Run the UI:

   python run_ui.py

4. Access: Open http://localhost:port in your browser.

---

Generated by Agent A2As - Powering the next generation of autonomous intelligence.