Building an Agentic Framework from scratch 🚀

Building an Agentic Framework for Smart, Reactive AI Agents

Artificial intelligence agents are increasingly part of modern software, but building them well is surprisingly tricky. In this article, I’ll share the design and development journey behind Reactive Agents, a framework I built to make reactive, adaptable AI agents easy to create while giving developers control, observability, and flexibility.

The Challenge: Why Build a New Framework?

I was honestly curious what it would take to build agents that can think and reason using their own strategies similar to how we go about tasks. Agentic frameworks at the time had little control over how to build decent agents with less code, so I wanted to try my take at it.

Most existing agent frameworks either:

• Treat agents as simple LLM + tool loops
  


• Require verbose or repetitive setup


• Limit flexibility in reasoning or strategy

From day one, I wanted something different:

• Agents that can think, act, and pivot mid-task


• Clear and type-safe APIs that are easy to reason about


• 
  Composable strategies to adapt to any agentic task


• Observable events so developers always know what the agent is doing and why
  

The goal was simple: make building smart, reactive AI agents intuitive, safe, and powerful, without sacrificing flexibility.

Core Principles of Reactive Agents

When designing the framework, I focused on several key principles:

1. Reactive Decision-Making

• Agents respond to task inputs and intermediate results rather than following a fixed plan.


• Built-in reflection allows them to pivot strategies if outcomes differ from expectations.

1. Tool Integration and MCP Support

• Agents can execute custom Python tools or leverage MCP servers for modular workflows.


• This enables distributed, multi-tool pipelines without complex orchestration.

1. Observability and Transparency

• Every agent action emits observable events.


• Developers can track reasoning, tool usage, and decision paths in real time.

1. Composability and Type Safety

• Reasoning strategies are modular, easy to swap, extend, or combine.


• Type-safe APIs reduce runtime errors and make development predictable.

1. Ease of Use

• The builder pattern provides a clean, minimal boilerplate setup.


• Quick startup time and wide model support make experimentation fast and rewarding.

Designing the Reactive Loop

At the heart of the framework is the reactive loop, which guides how an agent processes tasks:

1. 
   Receive Task → Agent gets input from the user or system


2. 
   Reasoning Layer → Decide which tools or strategies to use


3. 
   Tool Execution → Run custom or MCP-based tools


4. 
   Observe Feedback → Track events, results, and outputs


5. 
   Reflect & Adapt → Update strategy if needed, then repeat

This architecture ensures agents are not static. They learn and adapt in-flight, making them suitable for a wide range of agentic tasks.

Diagram Concept:

Task Input → Reasoning → Tool Execution → Observation → Reflection → Next Action

Implementation Highlights

While building Reactive Agents, a few design choices stood out:

• 
  Builder Pattern: Simple, readable agent creation.


• 
  Composable Strategies: Swap reasoning modules without rewriting the agent.


• 
  Observable Events: Makes debugging and insight seamless.


• 
  Type-Safe APIs: Catch errors early, improve developer confidence.


• 
  MCP Integration: Supports distributed agent architectures and modular workflows.

These choices collectively differentiate the framework from simpler orchestration layers or monolithic agent implementations.

Example: Minimal Reactive Agent

Below is an accurate, documented-aligned example showing a reactive agent using both a custom Python tool and an MCP tool:

import asyncio

from reactive_agents.agents import ReactAgentBuilder

from reactive_agents.tools.decorators import tool



# Define a simple custom tool

@tool(description="Greet a user")

async def greet(name: str) -> str:

    """Use this tool to greet the user by their provided name"""

    return f"Hello, {name}! Welcome to Reactive Agents."



async def main():

    agent = await (

        ReactAgentBuilder()

        .with_name("DemoAgent")

        .with_model("ollama:qwen3:4b")          # Example model string

        .with_tools(["brave-search", greet])  # Auto-detects MCP tools vs custom tools

        .with_observable_events()              # Track events

        .build()

    )



    result = await agent.run(

        "Greet a new user and fetch latest news about AI."

    )

    print(result)



if __name__ == "__main__":

    asyncio.run(main())

This snippet demonstrates reactive reasoning, tool execution, and observable events while remaining digestible for new users.

Lessons Learned While Building the Framework

1. 
   Design for observability early – It’s hard to debug complex agents without event tracking.


2. 
   Make reasoning modular – Composable strategies allow experimentation without breaking existing code.


3. 
   Keep APIs intuitive – Developers should spend more time designing agents than wrestling with setup.


4. 
   Support multiple tools and providers – Flexibility is essential for real-world agentic tasks.

Looking Forward

Reactive Agents is alpha-stage, but production-ready. APIs may evolve, but the core principles are stable: reactive loops, composable reasoning, observability, and tool integration.

I hope this framework inspires developers to explore agentic AI in new ways, creating smarter applications that don’t just respond, but reason, act, and improve dynamically.

Get Involved

Try it, star the repo, or contribute:

• GitHub: https://github.com/tylerjrbuell/reactive-agents
  

Whether it’s extending reasoning strategies, adding tools, or improving observability, your contributions help shape the next generation of reactive AI agents.