Tích hợp Python Agent

Các Python agent có thể trả lời câu hỏi của người dùng và chạy tự động hóa bằng cách gọi API V1 công khai của Sellfern từ các công cụ phía server. Giữ cho agent giới hạn trong các endpoint và schema được liệt kê trong Tham chiếu API.

Yêu cầu trước

Python 3.11 trở lên
Một khóa API Sellfern có các phạm vi tối thiểu cần thiết cho mục tiêu của người dùng
Một framework agent hoặc SDK model bạn chọn

Lưu cấu hình

Lưu secret trong biến môi trường trên server hoặc trình chạy tự động hóa.

export SELLFERN_API_KEY="your_api_key_here"
export SELLFERN_API_URL="https://api.sellfern.com"

Không commit khóa, không echo vào log, không đưa vào prompt, hoặc không phơi bày cho mã trình duyệt.

Gọi API phía server

Các hàm công cụ Python của bạn nên gửi khóa API Sellfern qua header x-api-key.

import os
import requests

SELLFERN_API_URL = os.environ.get("SELLFERN_API_URL", "https://api.sellfern.com")
SELLFERN_API_KEY = os.environ["SELLFERN_API_KEY"]


def sellfern_get(path: str, params: dict | None = None) -> dict:
    response = requests.get(
        f"{SELLFERN_API_URL}{path}",
        headers={"x-api-key": SELLFERN_API_KEY},
        params=params,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

Chỉ truyền các đường dẫn có trong /api-reference. Nếu một ví dụ hoặc yêu cầu của người dùng yêu cầu một bề mặt bị hoãn, hãy đề nghị người dùng xác nhận sự khả dụng của endpoint trong Tham chiếu API trước khi tiếp tục.

Thiết kế định nghĩa công cụ an toàn

Khi phơi bày các hành động Sellfern cho agent:

Giao cho mỗi công cụ một nhiệm vụ hẹp.
Khớp schema đầu vào của công cụ với Tham chiếu API.
Yêu cầu phạm vi tối thiểu cần thiết cho công cụ đó.
Với công cụ ghi, đính kèm header Idempotency-Key và dùng lại cho các lần retry của cùng thao tác logic.
Trả mã lỗi Sellfern cho agent mà không suy đoán về tài nguyên ẩn hoặc endpoint không được hỗ trợ.

Quy trình của agent

Đọc https://docs.sellfern.com/llms.txt để khám phá tài liệu liên quan.
Đọc trang sản phẩm hoặc trang nhà phát triển giải thích mục tiêu của người dùng.
Xác nhận endpoint và schema trong /api-reference.
Gọi công cụ Sellfern nhỏ nhất cần thiết.
Nếu Sellfern trả về 403 missing_scope, hãy yêu cầu người dùng cung cấp khóa với phạm vi bổ sung tối thiểu.
Nếu Sellfern trả về 404 not_found, đừng suy luận rằng tài nguyên tồn tại ở một tổ chức khác.

Mở rộng agent

Trước khi thêm công cụ mới, hãy kiểm tra Tham chiếu API V1. Các ví dụ cũ có thể đề cập đến các quy trình hàng loạt, đồng bộ, nhập, xử lý đơn, tài chính hoặc nội bộ không có sẵn cho V1 công khai. Nếu endpoint không có, hãy để công cụ tắt và giải thích rằng người dùng nên xác nhận sự khả dụng trong /api-reference.

​Yêu cầu trước

​Lưu cấu hình

​Gọi API phía server

​Thiết kế định nghĩa công cụ an toàn

​Quy trình của agent

​Mở rộng agent