Skip to content

Commit b16c564

Browse files
amineremacheamineremache
committed
feat(samples): add real-estate-agent sample
This commit introduces a new, self-contained sample for a real-estate agent. The sample demonstrates an agent capable of understanding natural language queries to search for rental properties. It is composed of three services orchestrated with Docker Compose: - A core Python A2A agent (`real-estate-agent`). - A Node.js MCP tool server (`dafty-mcp`) for interacting with a real-estate service. - A local LLM service (`ollama`) for natural language understanding. The sample is fully self-contained, with all necessary code and configuration included. The README provides detailed instructions for setup, usage, and testing, and directs contributions back to the original source repositories.
1 parent e2d685b commit b16c564

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

53 files changed

+15225
-0
lines changed

‎samples/python/agents/real_estate_agent/.dockerignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.git
2+
.gitignore
3+
tests
4+
.env
5+
.vscode
6+
__pycache__
7+
*.pyc

‎samples/python/agents/real_estate_agent/.env.example‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# The port the server will run on
2+
PORT=3001
3+
4+
# A secret key to authenticate requests
5+
API_KEY=your-secret-api-key
6+
7+
# The URL of the MCP server
8+
MCP_SERVER_URL=http://localhost:4000/sse
9+
10+
11+
# Your ngrok authtoken
12+
NGROK_AUTHTOKEN=your_ngrok_authtoken_here

‎samples/python/agents/real_estate_agent/.gitignore‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Byte-compiled / optimized / DLL files
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
6+
# C extensions
7+
*.so
8+
9+
# Distribution / packaging
10+
.Python
11+
build/
12+
develop-eggs/
13+
dist/
14+
downloads/
15+
eggs/
16+
.eggs/
17+
lib/
18+
lib64/
19+
parts/
20+
sdist/
21+
var/
22+
wheels/
23+
*.egg-info/
24+
.installed.cfg
25+
*.egg
26+
MANIFEST
27+
28+
# PyInstaller
29+
# Usually these files are written by a python script from a template
30+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
31+
*.manifest
32+
*.spec
33+
34+
# Installer logs
35+
pip-log.txt
36+
pip-delete-this-directory.txt
37+
38+
# Unit test / coverage reports
39+
htmlcov/
40+
.tox/
41+
.nox/
42+
.coverage
43+
.coverage.*
44+
.cache
45+
nosetests.xml
46+
coverage.xml
47+
*.cover
48+
.hypothesis/
49+
.pytest_cache/
50+
51+
# Translations
52+
*.mo
53+
*.pot
54+
55+
# Django stuff:
56+
*.log
57+
local_settings.py
58+
db.sqlite3
59+
60+
# Flask stuff:
61+
instance/
62+
.webassets-cache
63+
64+
# Scrapy stuff:
65+
.scrapy
66+
67+
# Sphinx documentation
68+
docs/_build/
69+
70+
# PyBuilder
71+
target/
72+
73+
# Jupyter Notebook
74+
.ipynb_checkpoints
75+
76+
# IPython
77+
profile_default/
78+
ipython_config.py
79+
80+
# pyenv
81+
.python-version
82+
83+
# celery beat schedule file
84+
celerybeat-schedule
85+
86+
# SageMath parsed files
87+
*.sage.py
88+
89+
# Environments
90+
.env
91+
.venv
92+
env/
93+
venv/
94+
ENV/
95+
env.bak/
96+
venv.bak/
97+
98+
# Spyder project settings
99+
.spyderproject
100+
.spyderworkspace
101+
102+
# Rope project settings
103+
.ropeproject
104+
105+
# mkdocs documentation
106+
/site
107+
108+
# mypy
109+
.mypy_cache/
110+
.dmypy.json
111+
dmypy.json
112+
113+
# Pyre type checker
114+
.pyre/
115+
116+
.env
117+
.session

‎samples/python/agents/real_estate_agent/CHANGELOG.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [0.1.2] - 2025-07-06
9+
10+
### Added
11+
- Deployment scripts for Google Cloud Platform.
12+
- `ngrok` integration for creating a public URL for the agent.
13+
- `gcp_setup.sh` to set up the environment on a GCP VM.
14+
- `gcp_initial_vm_setup.sh` and `gcp_startup_service.sh` for service configuration.
15+
16+
### Changed
17+
- Updated `docker-compose.yml` to use a dedicated network and handle environment variables for deployment.
18+
- The application now listens on `::` to accept connections from any IP address.
19+
- `agent_card.py` now uses an environment variable for the agent's public URL.
20+
- Updated `README.md` with deployment instructions for GCP.
21+
22+
## [0.1.1] - 2025-07-05
23+
24+
### Added
25+
- Integrated `ollama` with the `tinydolphin` model to parse natural language queries into structured JSON.
26+
- A new `parse_query` tool in the `dafty-mcp` to handle query parsing.
27+
28+
### Changed
29+
- The `agent_executor` now calls the `parse_query` tool before searching for properties.
30+
- The `dafty-mcp` client now has a generic `call_tool` method.
31+
- Updated `docker-compose.yml` to include the `ollama` and `ollama-setup` services.

‎samples/python/agents/real_estate_agent/Dockerfile‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Use an official Python runtime as a parent image
2+
FROM python:3.13-slim
3+
4+
# Set the working directory in the container
5+
WORKDIR /usr/src/app
6+
7+
# Copy the requirements file to the working directory
8+
COPY requirements.txt ./
9+
10+
# Install any needed packages specified in requirements.txt
11+
RUN pip install --no-cache-dir -r requirements.txt gunicorn
12+
13+
# Bundle app source
14+
COPY . .
15+
16+
# Create a non-root user and switch to it
17+
RUN useradd --create-home appuser
18+
USER appuser
19+
20+
# Set environment variables
21+
ENV PYTHONUNBUFFERED=1
22+
23+
# Your app binds to port 3001, so expose that
24+
EXPOSE 3001
25+
26+
# Define the command to run your app
27+
CMD ["gunicorn", "-w", "2", "-k", "uvicorn.workers.UvicornWorker", "main:app", "--bind", "[::]:3001", "--access-logfile", "-", "--error-logfile", "-", "--log-level", "info"]

‎samples/python/agents/real_estate_agent/LICENSE‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
ISC License
2+
3+
Copyright (c) 2025, Amine REMACHE <[email protected]>
4+
5+
Permission to use, copy, modify, and/or distribute this software for any
6+
purpose with or without fee is hereby granted, provided that the above
7+
copyright notice and this permission notice appear in all copies.
8+
9+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10+
WITH REGARD to THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11+
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12+
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13+
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14+
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15+
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

‎samples/python/agents/real_estate_agent/README.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Real-Estate Agent (A2A) Sample
2+
3+
![Real Estate Agent Banner](assets/a2a-real-estate-agent-banner.png)
4+
5+
This sample demonstrates a sophisticated real-estate agent based on the Agent-to-Agent (A2A) protocol. The agent is capable of understanding natural language queries, performing filtered searches for rental properties, and returning structured results.
6+
7+
## 🔗 Original Source and Contributions
8+
9+
This sample is a snapshot of an active open-source project. For the latest updates, to report issues, or to contribute, please visit the original repositories:
10+
11+
* **Real-Estate Agent:** `https://github.com/amineremache/robolancerai-real-estate-agent`
12+
* **Dafty MCP Server:** `https://github.com/amineremache/dafty-mcp`
13+
14+
We encourage you to contribute directly to the source projects!
15+
16+
## 🏛️ Architecture
17+
18+
The system is composed of three main services orchestrated with `docker-compose`:
19+
20+
1. **`real-estate-agent`**: The core Python A2A agent that handles user requests and orchestrates tool calls.
21+
2. **`dafty-mcp`**: A Node.js/TypeScript MCP (Model Context Protocol) tool server that provides the tools for interacting with the Daft.ie rental service. It includes a web scraper and an intelligent query parser.
22+
3. **`ollama`**: A local LLM service that runs the `tinydolphin` model to parse natural language queries into structured JSON.
23+
24+
## ✨ Features
25+
26+
- **Natural Language Understanding**: Uses a local LLM to parse user queries like "Find a 2-bed apartment in Dublin under €2000."
27+
- **Filtered Search**: Performs filtered searches based on location, price, and number of bedrooms.
28+
- **Self-Contained Environment**: The entire application runs in a portable and isolated Docker environment.
29+
- **A2A Compliant**: Built on the A2A protocol for standardized agent communication.
30+
31+
## 🚀 Getting Started
32+
33+
### Prerequisites
34+
35+
- Docker and `docker-compose` must be installed.
36+
- You must have a `.env` file in the root of this sample directory. You can create one from the `.env.example` file and add your `API_KEY`.
37+
38+
### Installation and Running
39+
40+
1. **Navigate to the sample directory:**
41+
```bash
42+
cd samples/python/agents/real_estate_agent
43+
```
44+
45+
2. **Build and start the services:**
46+
```bash
47+
docker-compose up --build
48+
```
49+
50+
3. **The services will now be running:**
51+
* The `real-estate-agent` will be available on port `3001`.
52+
* The `dafty-mcp` and `ollama` services will be running in the background.
53+
54+
## 🧪 Testing the Agent
55+
56+
You can send a request to the agent using `curl`. The following example demonstrates how to search for a 2-bedroom apartment in Dublin for under €2000.
57+
58+
```bash
59+
curl -X POST http://localhost:3001/ \
60+
-H "Content-Type: application/json" \
61+
-H "Authorization: Bearer <YOUR_API_KEY>" \
62+
-d '{
63+
"jsonrpc": "2.0",
64+
"id": "1",
65+
"method": "message/send",
66+
"params": {
67+
"message": {
68+
"messageId": "1",
69+
"role": "user",
70+
"parts": [
71+
{
72+
"kind": "text",
73+
"text": "Find a 2-bed apartment in Dublin under €2000."
74+
}
75+
]
76+
}
77+
}
78+
}' > results.json
79+
```
80+
81+
The results of the query will be saved to a `results.json` file in your project directory.

‎samples/python/agents/real_estate_agent/assets/a2a-real-estate-agent-banner.png‎

805 KB
Loading

‎samples/python/agents/real_estate_agent/dafty-mcp/.dockerignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
node_modules
2+
.session
3+
.git
4+
.vscode
5+
.idea
6+
npm-debug.log*
7+
yarn-debug.log*
8+
yarn-error.log*
9+
lerna-debug.log*
10+
.pnpm-debug.log*
11+
tests

0 commit comments

Comments
 (0)