A2A-MCP-RealEstate: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A2A (Application-to-Application) Agent for inter-service communication. This Python FastAPI application provides a framework for agents to communicate with each other, exchange data, and coordinate activities.

Development Commands

# Install dependencies
pip install -r requirements.txt

# Start development server with auto-reload
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Start production server
uvicorn app.main:app --host 0.0.0.0 --port 8000

# Alternative using pyproject.toml scripts
python -m pip install -e .
python -m app.main  # or use the configured scripts

# Run tests (when pytest is configured)
pytest

# Format code (if black/flake8 are added)
black app/
flake8 app/

Project Structure

app/
├── agent/              # Core A2A agent implementation
│   ├── __init__.py
│   └── a2a_agent.py   # Main agent class with async communication
├── routes/            # FastAPI route handlers
│   ├── __init__.py
│   ├── agent_routes.py # Agent communication endpoints  
│   └── data_routes.py  # Sample data endpoints
├── data/              # Sample data and generators
│   ├── __init__.py
│   └── sample_data.py # Korean sample data with generators
├── utils/             # Utility modules
│   ├── __init__.py
│   ├── config.py      # Pydantic settings management
│   └── logger.py      # Loguru-based logging
└── main.py            # FastAPI application entry point

Architecture

Core Components

1. A2AAgent Class (app/agent/a2a_agent.py): Async agent implementation

   • HTTP client-based communication with other agents
   • Pydantic models for message validation
   • Connection management and message queuing
   • Sample data generation and handling

2. FastAPI Routes:

   • /api/agent/* - Agent communication (handshake, messages, connections)
   • /api/data/* - Sample data endpoints (users, orders, products, system, metrics)
   • /health - Health check endpoint
   • /docs - Auto-generated OpenAPI documentation