AI Agent Observability: Logging và Tracing bằng Python

Khi xây dựng một AI Agent, việc mô hình tạo ra câu trả lời đúng trong một vài lần thử chưa đủ để chứng minh hệ thống đã sẵn sàng vận hành. Trong môi trường thực tế, agent có thể gọi sai công cụ, gặp lỗi kết nối, phản hồi chậm hoặc sử dụng nhiều lượt gọi LLM hơn dự kiến.

Nếu chỉ nhìn vào câu trả lời cuối cùng, rất khó xác định vấn đề bắt đầu từ đâu. Mô hình hiểu sai yêu cầu, MCP Server gặp lỗi hay ứng dụng điều phối xử lý kết quả không đúng cách đều có thể dẫn đến biểu hiện tương tự.

AI Agent Observability giúp đội ngũ phát triển quan sát những gì xảy ra bên trong hệ thống. Thông qua logging, tracing và metrics, chúng ta có thể theo dõi hoạt động của agent, phát hiện lỗi và đưa ra quyết định cải thiện dựa trên dữ liệu.

Bài viết này sẽ giới thiệu các khái niệm cốt lõi, hướng dẫn ghi log bằng Python, theo dõi thời gian gọi MCP tool và trình bày cách áp dụng tracing khi phát triển AI Agent.

1. AI Agent Observability là gì?

Observability, hay khả năng quan sát hệ thống, là khả năng hiểu trạng thái và hành vi bên trong của một ứng dụng thông qua các dữ liệu mà ứng dụng tạo ra khi hoạt động.

Đối với AI Agent, những dữ liệu cần quan sát có thể bao gồm:

• Yêu cầu ban đầu của người dùng.
• Các lượt gọi LLM và trạng thái phản hồi.
• Công cụ được lựa chọn và thời điểm thực thi.
• Thời gian xử lý của từng bước.
• Lỗi từ mô hình, mạng, MCP Client hoặc MCP Server.
• Số lượt gọi công cụ và lượng token sử dụng, nếu nhà cung cấp cung cấp dữ liệu này.
• Kết quả cuối cùng và trạng thái hoàn thành nhiệm vụ.

Ví dụ, một AI Agent được giao nhiệm vụ tra cứu thông tin khóa học có thể trả lời chậm. Nếu chỉ kiểm tra câu trả lời cuối cùng, chúng ta chưa biết nguyên nhân là do LLM mất nhiều thời gian suy luận, MCP Server truy vấn dữ liệu chậm hay ứng dụng phải gọi công cụ nhiều lần.

Observability giúp tách luồng xử lý thành các bước có thể kiểm tra, từ đó xác định nguyên nhân thay vì chỉ phỏng đoán.

2. Phân biệt Logging, Tracing và Metrics

Logging, tracing và metrics đều phục vụ việc theo dõi hệ thống, nhưng mỗi loại cung cấp một góc nhìn khác nhau.

Ba thành phần này bổ sung cho nhau. Logging cho biết sự kiện nào đã xảy ra, tracing cho biết các sự kiện liên kết với nhau ra sao, còn metrics giúp đánh giá xu hướng hoạt động của toàn hệ thống.

3. Vì sao AI Agent cần Observability?

3.1. Phát hiện lỗi trong quy trình nhiều bước

Một nhiệm vụ có thể gồm nhiều lượt gọi LLM và nhiều lần sử dụng công cụ. Nếu bước thứ ba thất bại, thông tin về bước thứ nhất và thứ hai có thể giúp xác định chính xác vấn đề.

3.2. Phát hiện độ trễ bất thường

Độ trễ của toàn bộ nhiệm vụ có thể đến từ nhiều thành phần. Theo dõi thời gian riêng của từng bước giúp xác định nên tối ưu lời gọi LLM, truy vấn dữ liệu hay kết nối với dịch vụ bên ngoài.

3.3. Kiểm soát chi phí

Việc ghi nhận số lượt gọi mô hình và lượng token sử dụng, khi có dữ liệu phù hợp, giúp phát hiện những quy trình gọi LLM quá nhiều lần. Các thông tin này cũng hỗ trợ so sánh những cách thiết kế agent khác nhau.

3.4. Tăng độ tin cậy

Log và trace giúp đội ngũ phát triển tái hiện vấn đề, hiểu nguyên nhân và kiểm tra xem bản sửa lỗi có cải thiện hành vi của agent hay không.

4. Logging trong Python với module logging

Python cung cấp sẵn module logging, vì vậy bạn có thể bắt đầu ghi log mà không cần cài thư viện bên ngoài.

Ví dụ sau tạo logger và ghi lại các sự kiện cơ bản của một tác vụ AI Agent:

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(name)s %(message)s"
)

logger = logging.getLogger("ai_agent")

logger.info("Agent started")
logger.info("Tool call started: search_courses")
logger.warning("Tool response is empty")
logger.error("Tool execution failed")

Trong ví dụ này:

• DEBUG: thông tin chi tiết phục vụ quá trình phát triển và tìm lỗi.
• INFO: các sự kiện thông thường trong quá trình chạy.
• WARNING: tình huống bất thường nhưng chưa nhất thiết làm tác vụ thất bại.
• ERROR: một thao tác không thể hoàn thành như dự kiến.
• CRITICAL: lỗi nghiêm trọng có thể ảnh hưởng lớn đến hoạt động của ứng dụng.

Trong môi trường thực tế, nên bổ sung mã yêu cầu, tên công cụ, thời gian thực thi và trạng thái kết quả. Không nên ghi toàn bộ nội dung prompt, dữ liệu cá nhân hoặc API key vào log nếu không thực sự cần thiết.

5. Theo dõi thời gian gọi MCP tool bằng Python

Một ứng dụng AI Agent có thể sử dụng MCP Client để gọi công cụ từ MCP Server. Theo dõi thời gian bắt đầu, thời gian kết thúc và trạng thái lỗi sẽ giúp xác định những lời gọi có độ trễ cao.

Ví dụ dưới đây sử dụng MCP Python SDK v2 và một MCP Server chạy qua Streamable HTTP tại địa chỉ minh họa http://localhost:8000/mcp. Bạn cần thay địa chỉ này bằng endpoint thực tế của mình.

import asyncio
import logging
from time import perf_counter
from mcp import Client

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(name)s %(message)s"
)

logger = logging.getLogger("mcp_monitor")


async def call_tool_with_logging(client, tool_name, arguments):
    start = perf_counter()

    logger.info("Tool call started: %s", tool_name)

    try:
        result = await client.call_tool(tool_name, arguments)

        elapsed = perf_counter() - start

        if result.isError:
            logger.error(
                "Tool returned an error: %s duration=%.3fs",
                tool_name,
                elapsed
            )
        else:
            logger.info(
                "Tool call completed: %s duration=%.3fs",
                tool_name,
                elapsed
            )

        return result

    except Exception:
        elapsed = perf_counter() - start

        logger.exception(
            "Tool call failed: %s duration=%.3fs",
            tool_name,
            elapsed
        )

        raise


async def main():
    async with Client("http://localhost:8000/mcp") as client:
        result = await call_tool_with_logging(
            client,
            "search_courses",
            {"keyword": "Python"}
        )

        print(result)


if __name__ == "__main__":
    asyncio.run(main())

Đây là ví dụ giám sát một lần gọi tool, không phải một AI Agent hoàn chỉnh. MCP Server cần thực sự cung cấp tool search_courses và nhận tham số keyword như trong ví dụ.

Hàm perf_counter() đo khoảng thời gian đã trôi qua. Nếu tool thất bại do ngoại lệ, logger.exception() ghi thông tin lỗi cùng traceback để hỗ trợ điều tra.

Lưu ý rằng result.isError biểu thị kết quả tool được trả về với trạng thái lỗi theo giao thức. Đây là trường hợp khác với ngoại lệ phát sinh khi kết nối hoặc thực thi. Hệ thống nên xử lý cả hai trường hợp.

6. Tracing: Theo dõi toàn bộ vòng đời một yêu cầu

Logging riêng lẻ chưa thể hiện đầy đủ mối liên hệ giữa các bước. Tracing giải quyết vấn đề này bằng cách gắn các hoạt động liên quan vào cùng một trace.

Ví dụ, với yêu cầu “Tìm khóa học Python và tóm tắt nội dung”, một trace có thể gồm các span như sau:

1. Agent run: bắt đầu xử lý yêu cầu.
2. LLM generation: mô hình phân tích yêu cầu và đề xuất gọi tool.
3. MCP tool call: ứng dụng gọi công cụ tìm khóa học.
4. Tool result: nhận kết quả từ MCP Server.
5. LLM generation: mô hình tổng hợp dữ liệu và tạo câu trả lời.
6. Agent run completed: ghi nhận trạng thái hoàn thành.

Mỗi span có thể ghi nhận thời điểm bắt đầu, thời điểm kết thúc, trạng thái và những thuộc tính phù hợp. Các span được liên kết với nhau giúp người phát triển biết bước nào chiếm nhiều thời gian hoặc phát sinh lỗi.

Một số hệ thống tracing còn hỗ trợ hiển thị cây thực thi, thông tin tool call, đầu ra của mô hình và quan hệ giữa các bước. Tuy nhiên, dữ liệu hiển thị cụ thể phụ thuộc vào framework và cấu hình của ứng dụng.

7. Sử dụng tracing với OpenAI Agents SDK

Nếu xây dựng agent bằng OpenAI Agents SDK, bạn có thể tận dụng hệ thống tracing tích hợp thay vì tự triển khai toàn bộ cơ chế ghi nhận các bước thực thi.

Theo tài liệu chính thức, tracing có thể ghi nhận những hoạt động như lượt gọi mô hình, lời gọi công cụ, handoff giữa các agent, guardrails và các span tùy chỉnh. Các trace hỗ trợ việc kiểm tra luồng xử lý và xác định nguyên nhân của những lần chạy không như mong đợi.

Để bắt đầu, hãy tham khảo:

• OpenAI Agents SDK — tài liệu hướng dẫn
• OpenAI — Tracing
• OpenAI — Integrations and Observability

Quy trình sử dụng ở mức tổng quát:

1. Xây dựng agent và khai báo các công cụ được phép sử dụng.
2. Chạy agent với một yêu cầu thử nghiệm.
3. Mở trace tương ứng trong công cụ quan sát được hỗ trợ.
4. Kiểm tra các lượt gọi mô hình, tool call, thời gian và trạng thái.
5. Sửa lỗi, chạy lại và so sánh kết quả.

Tracing không tự động bảo đảm agent trả lời đúng. Nó cung cấp dữ liệu để hiểu quá trình thực thi, từ đó giúp đánh giá và cải thiện hệ thống.

8. Metrics quan trọng khi vận hành AI Agent

Ngoài log và trace, bạn nên xác định một nhóm metrics phù hợp với mục tiêu của ứng dụng.

Không nên chỉ sử dụng thời gian phản hồi trung bình. Các phân vị như p50, p95 và p99 có thể giúp phát hiện những yêu cầu chậm bất thường mà giá trị trung bình che khuất.

Ví dụ, p95 là mức thời gian mà khoảng 95% các quan sát có thời gian nhỏ hơn hoặc bằng giá trị đó. Chỉ số này đặc biệt hữu ích khi một nhóm nhỏ yêu cầu có độ trễ rất cao.

9. Quy trình debugging khi AI Agent trả lời sai

Khi phát hiện một câu trả lời sai hoặc một tác vụ thất bại, hãy kiểm tra theo thứ tự để tránh thay đổi nhiều thành phần cùng lúc.

1. Kiểm tra đầu vào: người dùng đã cung cấp đủ thông tin chưa và ứng dụng có chuyển tiếp yêu cầu chính xác không?
2. Kiểm tra lượt gọi LLM: mô hình có chọn đúng hành động hoặc tool không?
3. Kiểm tra tham số: tên tool, kiểu dữ liệu và giá trị đầu vào có hợp lệ không?
4. Kiểm tra MCP Server: công cụ có chạy thành công và trả về dữ liệu mong đợi không?
5. Kiểm tra kết quả tool: ứng dụng có chuyển kết quả trở lại mô hình đúng cách không?
6. Kiểm tra câu trả lời cuối: mô hình có diễn giải đúng dữ liệu trả về không?
7. Chạy lại tình huống lỗi: dùng cùng đầu vào để xác nhận nguyên nhân và kiểm tra bản sửa.

Nếu có trace đầy đủ, bạn có thể lần theo luồng thực thi thay vì chỉ đọc log rời rạc. Nếu chưa có tracing, hãy bắt đầu bằng cách gắn mã yêu cầu vào log của các thành phần liên quan.

10. Bảo mật dữ liệu trong hệ thống Observability

Log và trace có thể chứa dữ liệu nhạy cảm, đặc biệt khi AI Agent xử lý tài liệu nội bộ, dữ liệu khách hàng hoặc thông tin xác thực.

• Không ghi API key, mật khẩu hoặc token truy cập vào log.
• Hạn chế lưu toàn bộ prompt và đầu ra nếu chúng chứa dữ liệu cá nhân hoặc thông tin nội bộ.
• Ẩn danh hoặc loại bỏ trường dữ liệu không cần thiết trước khi ghi nhận.
• Thiết lập quyền truy cập và thời hạn lưu trữ log, trace.
• Kiểm soát việc gửi dữ liệu đến các nền tảng quan sát bên ngoài.
• Chỉ ghi những thông tin cần thiết để debug và đánh giá chất lượng.

Observability cần giúp hệ thống dễ kiểm tra hơn mà không tạo thêm một điểm rủi ro về dữ liệu.

11. Lộ trình triển khai Observability cho AI Agent

Với một dự án nhỏ, bạn không cần bắt đầu bằng một hệ thống giám sát phức tạp. Có thể triển khai theo từng bước:

1. Bước 1 — Logging: ghi nhận thời điểm bắt đầu, kết thúc, trạng thái và lỗi của từng tác vụ.
2. Bước 2 — Định danh yêu cầu: sử dụng request ID để liên kết các log thuộc cùng một nhiệm vụ.
3. Bước 3 — Đo thời gian: theo dõi độ trễ của LLM, MCP tool và các dịch vụ bên ngoài.
4. Bước 4 — Tracing: kết nối các bước thành một luồng thực thi có thể kiểm tra.
5. Bước 5 — Metrics: tổng hợp độ trễ, tỷ lệ lỗi, số lượt gọi công cụ và các chỉ số chất lượng.
6. Bước 6 — Đánh giá định kỳ: kiểm thử bằng tập tình huống thực tế và so sánh kết quả sau mỗi lần thay đổi.

Với hệ thống lớn hơn, có thể cân nhắc chuẩn hóa dữ liệu telemetry bằng OpenTelemetry và tích hợp với nền tảng quan sát phù hợp. Hãy lựa chọn công cụ dựa trên hạ tầng, yêu cầu bảo mật, chi phí và mức độ phức tạp của ứng dụng.

12. Kết luận

AI Agent Observability là một phần quan trọng khi chuyển từ bản thử nghiệm sang hệ thống vận hành thực tế. Logging giúp ghi lại sự kiện, tracing cho thấy quan hệ giữa các bước xử lý, còn metrics cung cấp góc nhìn tổng hợp về hiệu năng và độ tin cậy.

Với Python, bạn có thể bắt đầu từ module logging và đo thời gian thực thi bằng perf_counter(). Khi hệ thống có nhiều lượt gọi LLM và MCP tools, tracing sẽ giúp điều tra lỗi và phân tích độ trễ hiệu quả hơn.

Hãy bắt đầu với những thông tin thực sự cần thiết, kiểm soát dữ liệu nhạy cảm và xây dựng quy trình kiểm thử rõ ràng. Một agent dễ quan sát sẽ dễ debug, dễ tối ưu và dễ duy trì hơn.

Nếu muốn phát triển thêm kỹ năng Python, AI và phân tích dữ liệu, bạn có thể tham khảo các chương trình tại MCNA Technology School:

• Combo Python
• Combo 5 khóa AI và Power BI

Tài liệu tham khảo:

• MCP Python SDK — tài liệu chính thức
• OpenAI Agents SDK
• OpenAI — Tracing
• OpenAI — Integrations and Observability