g-agentflow 0.1.6
Real-time visualization and cost tracking for AI Agents
License: Apache-2.0

AgentFlow 🕵️‍♂️

Real-time Observability & Visualization for AI Agents

AgentFlow is a lightweight, "drop-in" monitoring tool for agents built with the Google Gen AI Agent Development Kit (ADK). It visualizes your agent's thought process, tracks execution costs, and measures latency in real-time—without requiring a complex database setup.

🚀 Features

🔌 Zero-Config Instrumentation: Just wrap your root agent, and AgentFlow automatically discovers all tools and sub-agents recursively.

🕸️ Live Execution Graph: Watch your agent spawn sub-agents and call tools in a real-time interactive graph.

💰 Cost Estimation: Tracks token usage (Input/Output) and estimates cost per interaction.

⏱️ Latency Tracking: Identify which steps (LLM calls vs. Tool execution) are slowing down your agent.

💾 Persistence: Automatically saves execution history to agent_history.jsonl in your working directory. Data survives page refreshes.

📓 Colab Ready: specialized support for running the dashboard inside Google Colab or Jupyter Notebooks.

📦 Installation

# Install 
pip install g-agentflow

⚡ Quick Start

1. Instrument Your Agent

Add these two lines to your existing ADK agent definition file (e.g., agent.py):

from google.adk.agents import Agent
# [1] Import the wrapper
from agentflow.sdk import instrument_agent

# Your existing agent setup
root_agent = Agent(name="travel_concierge", ...)

# [2] Instrument the agent (Do this before running it)
root_agent = instrument_agent(root_agent)


2. Run the Dashboard

Open a terminal and run:

agentflow ui


This will start the visualization server at http://127.0.0.1:5000.

3. Run Your Agent

In a separate terminal, run your agent script:

python run_demo.py


Go to your browser. You will see the graph build itself live as you interact with the agent!

📓 Using with Google Colab

AgentFlow was designed to work seamlessly in notebook environments.

# Cell 1: Install
!pip install -e /content/agentflow  # Or pip install agentflow once published

# Cell 2: Start the Dashboard
from agentflow.colab import run_ui
run_ui() 
# The dashboard will appear right here in the output cell!

# Cell 3: Run your Agent
from agentflow.sdk import instrument_agent
# ... define and run your agent ...


🧠 How it Works

AgentFlow operates as a "Sidecar" to your main application:

The SDK: When you wrap your agent, AgentFlow injects decorators into the run, query, or __call__ methods of the agent and its tools.

The Interceptor: When the agent runs, these decorators capture inputs, outputs, timestamps, and payload sizes.

The Bridge: Data is sent via HTTP to the local AgentFlow server (running on port 5000).

The Visualizer: The server broadcasts events via WebSockets to the React frontend, which draws the nodes using ReactFlow.

Persistence

AgentFlow saves all events to a file named agent_history.jsonl in the directory where you ran the command.

To clear history: Click the "Clear History" button in the UI.

To share history: Simply send the .jsonl file to a colleague.

🤝 Contributing

Contributions are welcome! Please check out the agentflow directory for the source code.

Backend: agentflow/server.py (Flask + SocketIO)

Frontend: agentflow/static/app.js (React + ReactFlow)

SDK: agentflow/sdk.py (Python Decorators)

📄 License

Apache-2.0