langsmith-fetch

Tổng quan về langsmith-fetch skill

langsmith-fetch dùng để làm gì

langsmith-fetch là một debugging skill dành cho các ứng dụng LangChain và LangGraph cần điều tra chi tiết ở cấp trace từ LangSmith Studio. Thay vì yêu cầu assistant đoán vì sao một agent thất bại, skill này hướng assistant dùng CLI langsmith-fetch để lấy các LangSmith traces gần đây, kiểm tra runs, lỗi, tool calls, hoạt động của memory, thời gian thực thi và mức sử dụng token, rồi tóm tắt điều có khả năng đã xảy ra.

Phù hợp nhất để debug LangChain và LangGraph

langsmith-fetch skill hữu ích nhất khi bạn đã chạy agent với LangSmith tracing được bật và muốn chẩn đoán nhanh hơn trong quá trình phát triển hoặc rà soát sự cố. Skill này phù hợp với các câu hỏi như “vì sao agent này fail?”, “những tools nào đã được gọi?”, “vì sao latency cao?”, “memory có được cập nhật đúng không?”, hoặc “đã có chuyện gì xảy ra trong vài phút vừa rồi?”

Skill này kém hữu ích hơn nếu ứng dụng của bạn không gửi traces lên LangSmith, nếu bạn không có quyền truy cập project liên quan, hoặc nếu bạn cần profiling ở cấp code nằm ngoài dữ liệu trace.

Điểm khác biệt chính: phân tích agent dựa trên bằng chứng trước

Một prompt thông thường có thể mô tả các nguyên nhân có khả năng xảy ra, nhưng langsmith-fetch buộc assistant đi theo hướng dựa trên bằng chứng quan sát được: traces gần đây, trạng thái run, luồng thực thi, tool invocations, lỗi, timings và token usage. Nhờ vậy, đầu ra có tính hành động cao hơn khi debug hành vi của agent, đặc biệt trong những lỗi phụ thuộc vào trạng thái runtime thay vì chỉ dựa trên code tĩnh.

Cách sử dụng langsmith-fetch skill

Cài đặt và thiết lập langsmith-fetch

Cài CLI trước khi dựa vào skill:

pip install langsmith-fetch

Thiết lập thông tin xác thực LangSmith và project mà CLI cần truy vấn:

export LANGSMITH_API_KEY="your_langsmith_api_key"
export LANGSMITH_PROJECT="your_project_name"

Kiểm tra cả hai biến đều có sẵn trong shell nơi assistant hoặc lệnh terminal sẽ chạy:

echo $LANGSMITH_API_KEY
echo $LANGSMITH_PROJECT

Nếu các biến này bị thiếu hoặc trỏ sai project, skill có thể trả về kết quả debug rỗng hoặc gây hiểu lầm.

Những thông tin skill cần từ bạn

Để có kết quả tốt nhất, hãy cung cấp cho assistant mục tiêu debug, khoảng thời gian và triệu chứng lỗi. Một prompt yếu là: “debug my agent.” Một prompt tốt hơn là:

Use langsmith-fetch to inspect the last 15 minutes of traces in my LangSmith project. Focus on failed LangGraph runs, tool call errors, memory writes, latency spikes, and token usage. Summarize the likely root cause and list the trace evidence you used.

Các chi tiết hữu ích gồm:

• thời điểm lỗi ước lượng hoặc “last N minutes”
• tên agent, graph, chain hoặc endpoint
• hành vi kỳ vọng so với hành vi thực tế
• cần ưu tiên lỗi, tools, memory, hiệu năng hay chi phí
• bất kỳ user input hoặc run ID nào liên quan đến sự cố

Quy trình sử dụng langsmith-fetch trong thực tế

Một lệnh khởi đầu thường dùng là:

langsmith-fetch traces --last-n-minutes 5 --limit 5 --format pretty

Dùng lệnh này để phân loại nhanh sau một lỗi mới xảy ra. Hãy yêu cầu assistant báo cáo:

1. đã tìm thấy bao nhiêu traces
2. traces nào bị fail hoặc có dấu hiệu bất thường
3. tool calls cùng input/output của chúng khi có liên quan
4. các thao tác memory hoặc state nếu agent của bạn có dùng
5. mô hình latency và token usage
6. giả thuyết root cause ngắn gọn kèm bằng chứng

Để debug sâu hơn, hãy mở rộng khoảng thời gian hoặc tăng limit. Với các project nhiều nhiễu, hãy thu hẹp truy vấn theo ngữ cảnh project, khoảng thời gian, run name hoặc triệu chứng lỗi cụ thể.

File repository nên đọc trước

Upstream skill tập trung trong SKILL.md; trong phần xem trước repository không có các thư mục phụ lớn như scripts/, resources/ hay references/. Hãy đọc SKILL.md trước để hiểu các cụm từ kích hoạt dự kiến, điều kiện tiên quyết và các mẫu workflow. Điểm cần kiểm tra khi áp dụng không nằm ở độ phức tạp của repository, mà là môi trường LangSmith và quyền truy cập CLI của bạn đã được cấu hình sẵn hay chưa.

FAQ về langsmith-fetch skill

langsmith-fetch chỉ dành cho LangGraph phải không?

Không. Skill này được viết để debug agent cho cả LangChain và LangGraph. Nó đặc biệt hữu ích với kiểu thực thi dạng graph vì traces có thể cho thấy luồng node, tool calls, chuyển đổi state và điểm mà một run đi lệch khỏi kỳ vọng.

Vì sao cách này tốt hơn việc nhờ AI debug từ logs?

langsmith-fetch skill tốt hơn khi vấn đề có thể quan sát trong LangSmith traces. Skill cung cấp cho assistant một workflow cụ thể để lấy dữ liệu thực thi thay vì dựa vào logs được dán vào hoặc suy đoán. Bạn vẫn cần xem xét kết quả một cách thận trọng, nhưng phân tích sẽ bắt đầu từ các runs đã quan sát được thay vì lời khuyên debug chung chung.

Người mới có cần biết LangSmith để dùng không?

Người mới có thể dùng skill nếu đã có người bật LangSmith tracing và cung cấp đúng LANGSMITH_API_KEY cũng như LANGSMITH_PROJECT. Nếu chưa có thiết lập này, rào cản chính không phải là cách viết prompt mà là quyền truy cập môi trường. Hiểu cơ bản về traces, runs, tool calls và projects sẽ giúp bạn diễn giải đầu ra dễ hơn.

Khi nào không nên dùng langsmith-fetch?

Không nên dùng skill này cho các ứng dụng không được trace trong LangSmith, để debug hành vi chỉ xảy ra ở frontend, cho vấn đề database không được thể hiện trong traces, hoặc cho các project riêng tư mà môi trường assistant không nên truy cập credentials của LangSmith. Cũng nên tránh dùng khi bạn đã có run ID chính xác và cần kiểm tra thủ công trong LangSmith UI với ảnh chụp màn hình hoặc chú thích của team.

Cách cải thiện langsmith-fetch skill

Cải thiện prompt langsmith-fetch bằng phạm vi rõ hơn

Cải thiện chất lượng lớn nhất đến từ việc thu hẹp câu hỏi. Thay vì yêu cầu rà soát rộng, hãy nêu rõ quyết định bạn cần:

Check recent traces for failed tool calls in the payment support agent. Determine whether failures come from tool input formatting, tool timeout, or model planning. Include trace IDs or run names if available.

Cách này giúp assistant tách triệu chứng khỏi nguyên nhân tốt hơn và tránh tạo một bản tóm tắt chung chung cho mọi trace.

Đưa ra mục tiêu bằng chứng, không chỉ nêu triệu chứng

Hãy cho skill biết bằng chứng nào quan trọng. Khi debug độ tin cậy, hãy yêu cầu errors, retries, exception messages và bước thành công cuối cùng. Khi debug hiệu năng, hãy yêu cầu slow runs, tool calls kéo dài, model latency và token usage. Khi debug memory, hãy yêu cầu các thao tác read/write, context bị thiếu, state updates bất thường và liệu các bước sau có dùng thông tin đã lưu hay không.

Chú ý các kiểu lỗi thường gặp

Các vấn đề phổ biến gồm truy vấn sai LangSmith project, dùng khoảng thời gian quá ngắn, lấy quá ít traces hoặc xem một run bị fail là đại diện cho toàn bộ. Nếu kết quả trông rỗng, hãy xác nhận environment variables và mở rộng time window. Nếu kết quả quá nhiễu, hãy thu hẹp phạm vi theo agent name, thời gian hoặc triệu chứng. Nếu phần phân tích nghe có vẻ suy đoán, hãy yêu cầu assistant tách riêng “trace evidence” và “hypothesis.”

Lặp lại sau đầu ra đầu tiên

Sau lần sử dụng langsmith-fetch ban đầu, hãy đặt các câu hỏi tiếp theo để biến phân tích trace thành hành động kỹ thuật:

• “Which code path should I inspect first?”
• “What prompt or tool schema change would prevent this?”
• “Compare failed and successful traces in the same window.”
• “List the minimal reproduction from the trace.”
• “What metric should I monitor to catch this earlier?”

Điều này biến skill từ một công cụ xem trace thành một vòng lặp debug thực tế cho các agent LangChain và LangGraph.