Agent Service API

Hệ thống FastAPI đơn giản để quản lý và gọi các service agent với input/output: text, file (URL), image (URL).

Đặc điểm chính

• Input đơn giản: text, file (URL), image (URL)
• Output đơn giản: text, file (URL), image (URL)
• Auto-discovery: Tự động phát hiện và đăng ký agents mới
• Modular: Dễ dàng thêm agent mới

Cấu trúc dự án

FastAPI/
├── app/
│   ├── main.py              # Entry point của FastAPI
│   ├── api/
│   │   ├── router.py        # Router chính
│   │   └── v1/
│   │       └── agents.py    # API endpoints cho agents
│   ├── services/
│   │   ├── base.py          # BaseAgentService abstract class
│   │   ├── registry.py      # Auto-discovery và đăng ký agents
│   │   ├── agent_a.py       # LLM Agent
│   │   ├── agent_b.py       # Vision Agent  
│   │   └── file_agent.py    # File Processing Agent
│   ├── models/
│   │   └── schemas.py       # Pydantic models cho input/output
│   └── utils/
│       └── file_utils.py    # Utilities cho file operations
├── requirements.txt
├── test_api.py
└── README.md

Cài đặt và chạy

1. Cài đặt dependencies

pip install -r requirements.txt

2. Chạy server

uvicorn app.main:app --reload

Server sẽ chạy tại: http://localhost:8000

3. Xem API docs

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Schemas đơn giản

Request

{
  "text": "text content (optional)",
  "file": "https://example.com/file.pdf (optional)",
  "image": "https://example.com/image.jpg (optional)"
}

Response

{
  "text": "response text (optional)",
  "file": "https://example.com/output.pdf (optional)", 
  "image": "https://example.com/output.jpg (optional)"
}

Các Agent có sẵn

1. LLM Agent (llm_agent)

• Input: text
• Output: text
• Mô tả: Gọi Large Language Model để xử lý text

2. Vision Agent (vision_agent)

• Input: image (URL)
• Output: text (mô tả hình ảnh)
• Mô tả: Phân tích và mô tả hình ảnh

3. File Processing Agent (file_processing_agent)

• Input: file (URL)
• Output: text (phân tích file)
• Mô tả: Đọc và phân tích nội dung file

API Endpoints

GET /api/v1/agents/

Liệt kê tất cả agents có sẵn

POST /api/v1/agents/{agent_name}/process

Xử lý request với agent chỉ định

GET /api/v1/agents/{agent_name}/info

Lấy thông tin chi tiết về agent

Ví dụ sử dụng

1. Gọi LLM Agent

curl -X POST "http://localhost:8000/api/v1/agents/llm_agent/process" \
     -H "Content-Type: application/json" \
     -d '{
       "text": "Viết một câu chuyện ngắn về AI"
     }'

2. Gọi Vision Agent

curl -X POST "http://localhost:8000/api/v1/agents/vision_agent/process" \
     -H "Content-Type: application/json" \
     -d '{
       "image": "https://example.com/image.jpg"
     }'

3. Gọi File Processing Agent

curl -X POST "http://localhost:8000/api/v1/agents/file_processing_agent/process" \
     -H "Content-Type: application/json" \
     -d '{
       "file": "https://example.com/document.pdf"
     }'

Test API

Chạy script test:

python test_api.py

Thêm Agent mới

1. Tạo file mới trong app/services/ (ví dụ: my_agent.py)
2. Kế thừa từ BaseAgentService
3. Implement method process()
4. Agent sẽ tự động được đăng ký khi restart server

Ví dụ:

from .base import BaseAgentService
from app.models.schemas import AgentRequest, AgentResponse

class MyAgent(BaseAgentService):
    name = "my_agent"
    description = "Mô tả agent của tôi"

    async def process(self, request: AgentRequest) -> AgentResponse:
        # Xử lý input
        if request.text:
            result_text = f"Đã xử lý text: {request.text}"
            return AgentResponse(text=result_text)
        
        return AgentResponse(text="Không có input để xử lý")

Lợi ích của thiết kế đơn giản

• Dễ sử dụng: Request/Response chỉ có 3 trường: text, file, image
• Linh hoạt: Mỗi agent tự quyết định xử lý input nào và trả về output gì
• Mở rộng dễ dàng: Thêm agent mới chỉ cần 1 file Python
• Tự động: Auto-discovery agents không cần config thủ công