Danh sách tools của Agent

Đây là danh sách đầy đủ 19 tools mà Agent có thể sử dụng để tương tác với QGIS. Mỗi tool được ánh xạ tới một hoặc nhiều nhóm tính năng QGIS mà nó hỗ trợ.

Tính năng QGIS tham chiếu: https://docs.qgis.org/3.44/en/docs/about/features.html

Tổng quan 19 tools theo nhóm

📝 Note: 22 tools được đề cập trong tài liệu cũ, nhưng thực tế source code có 19 async functions. TODO: Cần xác nhận lại với team dev.

Chi tiết từng tool

1. list_layers — Liệt kê layer

Mô tả: Trả về danh sách tất cả layer đang mở trong dự án QGIS.

Input: Không có

Output: Danh sách tên layer + loại (vector/raster)

Nhóm QGIS: View data

Ví dụ câu hỏi:

Liệt kê tất cả layer đang mở

Có những layer nào trong dự án?

Layer nào là vector, layer nào là raster?

2. zoom_to_layer — Zoom tới layer

Mô tả: Di chuyển bản đồ và zoom vừa khít với extent của layer.

Input:

• layer_name (string, bắt buộc): Tên layer

Output: Bản đồ đã được zoom

Nhóm QGIS: Explore & compose

Ví dụ câu hỏi:

Zoom tới layer ranh giới tỉnh

Cho tôi xem toàn bộ layer lô rừng

3. zoom_to_features — Zoom tới feature

Mô tả: Zoom tới các feature thỏa điều kiện hoặc feature đã chọn.

Input:

• layer_name (string, bắt buộc)
• query (string, tùy chọn): QGIS expression
• selected_only (bool, tùy chọn): Chỉ zoom tới feature đang chọn

Output: Bản đồ đã zoom

Nhóm QGIS: Explore & compose

Ví dụ câu hỏi:

Zoom tới các lô rừng có diện tích > 100 ha

Pan tới feature đang được chọn

4. select_features — Chọn feature

Mô tả: Chọn các feature theo QGIS expression.

Input:

• layer_name (string, bắt buộc)
• query (string, bắt buộc): QGIS expression

Output: Số feature được chọn

Nhóm QGIS: Explore & compose

Ví dụ câu hỏi:

Chọn tất cả xã thuộc huyện Bắc Bình

Chọn lô rừng có trạng thái = "rừng tự nhiên"

5. highlight_features — Tô màu nổi bật

Mô tả: Highlight (tô màu) các feature thỏa điều kiện.

Input:

• layer_name (string, bắt buộc)
• query (string, bắt buộc): QGIS expression

Output: Feature được highlight trên bản đồ

Nhóm QGIS: Explore & compose

Ví dụ câu hỏi:

Highlight các huyện có tỷ lệ che phủ rừng > 50%

Tô màu đỏ cho thửa đất bị xâm phạm

6. set_layer_visibility — Ẩn/hiện layer

Mô tả: Bật hoặc tắt hiển thị của layer.

Input:

• layer_name (string, bắt buộc)
• visible (bool, bắt buộc): true = hiện, false = ẩn

Output: Layer được ẩn/hiện

Nhóm QGIS: Explore & compose

Ví dụ câu hỏi:

Ẩn layer đường giao thông

Hiện tất cả layer

Chỉ hiện các layer về rừng

7. get_layer_attributes — Đọc bảng thuộc tính

Mô tả: Đọc dữ liệu từ bảng thuộc tính của layer.

Input:

• layer_name (string, bắt buộc)
• limit (int, mặc định 10): Số dòng tối đa
• query (string, tùy chọn): Lọc theo expression
• selected_only (bool, tùy chọn): Chỉ feature đang chọn

Output: Bảng dữ liệu thuộc tính

Nhóm QGIS: Explore & compose

Ví dụ câu hỏi:

Cho tôi xem 10 dòng đầu của layer lô rừng

Đọc thuộc tính của tất cả feature đang chọn

8. set_layer_style — Style đơn giản

Mô tả: Thay đổi style cơ bản của layer (màu, viền, độ trong suốt).

Input:

• layer_name (string, bắt buộc)
• fill_color (string, tùy chọn): Màu nền (hex hoặc tên)
• stroke_color (string, tùy chọn): Màu viền
• stroke_width (float, tùy chọn): Độ dày viền
• opacity (float, tùy chọn): Độ trong suốt 0-1

Output: Layer đã được style

Nhóm QGIS: Explore & compose

Ví dụ câu hỏi:

Đổi màu layer xã thành xanh lá nhạt

Tăng độ dày viền lên 2px

Giảm độ trong suốt xuống 50%

9. set_layer_style_rule — Style rule-based

Mô tả: Tạo style rule-based với expression điều kiện.

Input:

• layer_name (string, bắt buộc)
• rule_name (string, bắt buộc): Tên rule
• expression (string, bắt buộc): QGIS expression
• fill_color, stroke_color, stroke_width, opacity (tùy chọn)

Output: Rule đã được thêm vào layer

Nhóm QGIS: Explore & compose

Ví dụ câu hỏi:

Tô màu xanh cho lô rừng có diện tích > 100 ha

Style rule: highlight đỏ cho thửa đất có rủi ro cháy cao

10. reorder_layer — Sắp xếp layer

Mô tả: Di chuyển layer lên trên hoặc xuống dưới layer khác.

Input:

• layer_name (string, bắt buộc): Layer cần di chuyển
• target_layer_name (string, bắt buộc): Layer đích
• position (string, mặc định ‘below’): ‘above’ hoặc ‘below’

Output: Layer panel được cập nhật

Nhóm QGIS: Explore & compose

Ví dụ câu hỏi:

Đưa layer lô rừng lên trên layer ranh giới

Đặt layer nhãn lên đầu

11. query_gis_data — Truy vấn SQL

Mô tả: Chạy SQL query trên dữ liệu của layer (qua OGR/SpatiaLite/PostGIS).

Input:

• sql_query (string, bắt buộc): Câu SQL

Output: Kết quả query dạng bảng

Nhóm QGIS: Analyze data

Ví dụ câu hỏi:

Tính tổng diện tích theo từng huyện

Đếm số lô rừng theo loại

Lưu ý: Cú pháp SQL tùy thuộc vào nguồn dữ liệu:

• Shapefile/GeoPackage: SQLite/SpatiaLite syntax
• PostGIS: PostgreSQL syntax
• TODO: Xác nhận backend query nào được hỗ trợ

12. web_search — Tìm kiếm web

Mô tả: Tìm kiếm thông tin trên web để hỗ trợ phân tích.

Input:

• query (string, bắt buộc): Từ khóa tìm kiếm

Output: Kết quả tìm kiếm

Nhóm QGIS: Analyze data

Ví dụ câu hỏi:

Tìm thông tin về quy trình kiểm kê rừng ở Việt Nam

Tham khảo chỉ số NDVI tiêu chuẩn cho rừng nhiệt đới

13. execute_qgis_python_script — Chạy Python script

Mô tả: Thực thi Python script trong QGIS Python Console.

Input:

• script (string, bắt buộc): Code Python
• confirm (bool, mặc định False): TODO - xác nhận trước khi chạy?

Output: Kết quả in ra từ script

Nhóm QGIS: Python Console

Ví dụ câu hỏi:

Chạy script Python để đếm số feature của tất cả layer

Tạo workflow import tự động bằng Python

⚠️ Cảnh báo bảo mật: Script có toàn quyền truy cập máy. Xem chi tiết tại Bài 10: Python Console.

14. inspect_map_visual — AI nhìn bản đồ

Mô tả: AI phân tích hình ảnh bản đồ hiện tại (dùng vision model).

Input:

• question (string, bắt buộc): Câu hỏi về bản đồ

Output: Phân tích bằng văn bản

Nhóm QGIS: Analyze data

Ví dụ câu hỏi:

Nhìn bản đồ này, khu vực nào có mật độ sông ngòi cao nhất?

Phân tích sự phân bố của các điểm đỏ trên bản đồ

💡 Mẹo: Kết hợp với screenshot để AI “nhìn” bản đồ hiện tại.

15. inspect_local_image — Phân tích ảnh

Mô tả: AI phân tích một file ảnh trên máy (dùng vision model).

Input:

• file_path (string, bắt buộc): Đường dẫn ảnh
• question (string, bắt buộc): Câu hỏi về ảnh

Output: Phân tích bằng văn bản

Nhóm QGIS: Analyze data

Ví dụ câu hỏi:

Phân tích ảnh viễn thám tại /data/sentinel2.tif

Mô tả ảnh chụp flycam tại /data/drone_img.jpg

16. read_local_document — Đọc tài liệu

Mô tả: Đọc nội dung file tài liệu (PDF, DOCX, TXT, …).

Input:

• file_path (string, bắt buộc): Đường dẫn file

Output: Nội dung file dạng text

Nhóm QGIS: Analyze data

Ví dụ câu hỏi:

Đọc file báo cáo tại /docs/bao_cao_2024.pdf

Tóm tắt file hướng dẫn kỹ thuật

⚠️ File lớn có thể bị giới hạn. TODO: Xác nhận giới hạn kích thước file.

17. qgis_find_file — Tìm file

Mô tả: Tìm file trong thư mục dự án QGIS.

Input:

• filename (string, bắt buộc): Tên file cần tìm

Output: Danh sách đường dẫn file

Nhóm QGIS: File operations

Ví dụ câu hỏi:

Tìm file ranh_gioi.shp trong dự án

File ranh_gioi_tinh nằm ở đâu?

18. qgis_list_dir — Liệt kê thư mục

Mô tả: Liệt kê nội dung thư mục.

Input:

• directory_path (string, bắt buộc): Đường dẫn thư mục

Output: Danh sách file và thư mục con

Nhóm QGIS: File operations

Ví dụ câu hỏi:

Có những file nào trong thư mục /data?

Liệt kê thư mục /data/raw

19. qgis_read_file — Đọc file

Mô tả: Đọc nội dung file (text, CSV nhỏ, …).

Input:

• file_path (string, bắt buộc): Đường dẫn file

Output: Nội dung file

Nhóm QGIS: File operations

Ví dụ câu hỏi:

Đọc file CSV tại /data/du_lieu.csv

Xem nội dung file log

20. qgis_grep_search — Tìm chuỗi trong file

Mô tả: Tìm chuỗi trong các file trong thư mục (giống grep).

Input:

• directory_path (string, bắt buộc)
• pattern (string, bắt buộc): Pattern cần tìm

Output: Danh sách file + dòng khớp

Nhóm QGIS: File operations

Ví dụ câu hỏi:

Tìm tất cả file có chứa "EPSG:4326" trong /data

Tìm file Python nào dùng import qgis.core

Nhóm tools theo chức năng

🗺️ Điều khiển bản đồ

• zoom_to_layer
• zoom_to_features

🎯 Select & Highlight

• select_features
• highlight_features

👁️ Quản lý hiển thị

• set_layer_visibility
• reorder_layer

📊 Phân tích dữ liệu

• get_layer_attributes
• query_gis_data
• inspect_map_visual
• inspect_local_image
• read_local_document
• web_search

🎨 Style & Symbology

• set_layer_style
• set_layer_style_rule

📁 Thao tác file

• list_layers
• qgis_find_file
• qgis_list_dir
• qgis_read_file
• qgis_grep_search

🐍 Tự động hóa

• execute_qgis_python_script

TODO cần bạn xác nhận

• Danh sách đầy đủ 19 hay 22 tools? Source code hiện tại có 19 async functions
• Có tool nào bị ẩn / deprecated không?
• Tool nào sắp tới sẽ thêm?
• Confirm chính sách confirm parameter trong execute_qgis_python_script

Liên kết

• Phân tích dữ liệu
• Khám phá bản đồ
• Python Console