Skip to content

Agent Code Detective

Josemalyson Oliveira edited this page Jun 27, 2026 · 1 revision

Agent Code Detective

The systematic methodology for reverse-engineering any AI agent open-source project.


Overview

Turns your agent into a "code detective" that can map architectures of projects like OpenHands, Aider, Cline, LangGraph, CrewAI, and more.

When to Use

  • Understanding a new codebase
  • Documenting existing architecture
  • Onboarding new team members
  • Learning from open-source projects

Trigger Phrases

  • "Me ajuda a entender o projeto X"
  • "Investigate this codebase"
  • "Map the architecture of X"
  • "How does this agent work?"

6-Phase Workflow

Phase Time Description
1. Territory Reconnaissance 15 min Read README, analyze dependencies, map folder structure
2. Entry Point 30 min Locate execution start, classify as CLI/HTTP/SDK/Worker
3. Follow the Trail 1h Find 6 universal components using grep patterns
4. Live Surveillance 1-2h Debug with 5 universal breakpoints
5. X-Ray Tracing 30 min Capture HTTP calls to LLM providers
6. Validate by Modifying 1h Make 3+ experiments to confirm understanding

Phase 1: Territory Reconnaissance (15 min)

Objectives

  • Understand what the project does
  • Identify the tech stack
  • Map the folder structure

Steps

  1. Read README.md and ARCHITECTURE.md (if exists)
  2. Analyze dependency manifests (pyproject.toml, package.json, etc.)
  3. Map folder structure
  4. Identify frameworks (langgraph, pydantic-ai, etc.)

Phase 2: Entry Point (30 min)

Objectives

  • Find where execution starts
  • Classify the application type

Steps

  1. Search for entry points:

    • Python: if __name__, app.command, cli()
    • TypeScript: createServer, app.listen, main()
    • Go: func main()
    • Rust: fn main()
  2. Classify as:

    • CLI — Command-line interface
    • HTTP — Web server
    • SDK — Library/package
    • Worker — Background process

Phase 3: Follow the Trail (1h)

The 6 Universal Components

Every AI agent has these components:

  1. Entry Point — Where execution starts
  2. Agent Loop — The main execution cycle
  3. LLM Client — Interface to language models
  4. Tool Registry — Available tools/functions
  5. Memory/State — Context management
  6. Prompt Manager — Template management

Grep Patterns

# Agent loop
grep -r "while True" --include="*.py"
grep -r "for.*in.*range" --include="*.py"

# LLM client
grep -r "openai\|anthropic\|langchain" --include="*.py"

# Tool registry
grep -r "@tool\|def.*tool\|register.*tool" --include="*.py"

Phase 4: Live Surveillance (1-2h)

The 5 Universal Breakpoints

BP Location Variables to Inspect
BP1 Input entry User message, context
BP2 LLM outbound call Prompt, model, params
BP3 LLM response Completion, tokens
BP4 Tool execution Tool name, args, result
BP5 Loop stop decision Exit condition, state

Progressive Tests

  1. No tool — Send a simple question
  2. Single tool — Request one specific action
  3. Multi-tool — Request complex workflow
  4. Forced error — Send invalid input

Phase 5: X-Ray Tracing (30 min)

Tools

  • mitmproxy — HTTP proxy for capturing requests
  • Langfuse — LLM observability platform
  • OpenTelemetry — Distributed tracing

Setup

# mitmproxy
mitmproxy --mode reverse:http://localhost:8080

# Environment variables
export ANTHROPIC_PROXY=http://localhost:8080
export OPENAI_BASE_URL=http://localhost:8080

Phase 6: Validate by Modifying (1h)

Experiments

  1. Add print statements — Trace execution flow
  2. Change a prompt — Observe behavior changes
  3. Add a new tool — Test extensibility
  4. Modify state — Test memory management

Output

A structured docs/investigation.md dossier with:

  1. Identity and entry point analysis
  2. 6 core components
  3. End-to-end flow visualization
  4. Observed patterns
  5. Metrics (lines of code, dependencies, etc.)
  6. Fragilities and risks
  7. Architectural decisions
  8. Open questions
  9. Transferable learnings

References


Last updated: June 2026