docs: add AGENTS.md for AI agent guidance
Document SDK layout, API mapping, and links to FastGPT OpenAPI (应用管理). Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Xin Wang
112
AGENTS.md
Normal file
112
AGENTS.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# AGENTS.md — FastGPT Python SDK
|
||||
|
||||
Guidance for AI agents working in this repository.
|
||||
|
||||
## What this repo is
|
||||
|
||||
Python client (`fastgpt_client`) for [FastGPT OpenAPI](https://doc.fastgpt.io/). It wraps HTTP calls with `httpx`, returns `httpx.Response` objects, and provides sync/async clients plus streaming helpers.
|
||||
|
||||
**Package layout**
|
||||
|
||||
| Path | Role |
|
||||
|------|------|
|
||||
| `fastgpt_client/client.py` | `ChatClient`, `AppClient` (sync) |
|
||||
| `fastgpt_client/async_client.py` | `AsyncChatClient`, `AsyncAppClient` |
|
||||
| `fastgpt_client/base_client.py` | Auth, retries, validation |
|
||||
| `fastgpt_client/streaming.py` | `iter_stream_events`, `aiter_stream_events` |
|
||||
| `docs/` | MkDocs user docs (source of truth for examples) |
|
||||
| `tests/` | `pytest` suite |
|
||||
|
||||
## Official API reference
|
||||
|
||||
Use these when adding or verifying endpoints (do not guess paths or payloads):
|
||||
|
||||
| Area | Interactive OpenAPI | Written docs |
|
||||
|------|---------------------|--------------|
|
||||
| **应用管理** (app logs, analytics) | [cloud.fastgpt.cn/openapi — 应用管理](https://cloud.fastgpt.cn/openapi#tag/%E5%BA%94%E7%94%A8%E7%AE%A1%E7%90%86) | [应用接口](https://doc.fastgpt.io/zh-CN/openapi/app) |
|
||||
| Chat / conversations | [Chat API](https://doc.fastgpt.io/docs/introduction/development/openapi/chat) | `docs/api/chat_client.md` |
|
||||
|
||||
**Auth:** `Authorization: Bearer {api_key}` on every request.
|
||||
|
||||
**Base URLs**
|
||||
|
||||
- **SaaS (cloud):** `https://cloud.fastgpt.cn` — app analytics routes live under `/api/proApi/...`
|
||||
- **Self-hosted:** your deployment origin (default in code: `http://localhost:3000`)
|
||||
|
||||
Pass `base_url` to the client; paths in code are relative (e.g. `/api/proApi/core/app/logs/getChartData`).
|
||||
|
||||
## SDK ↔ API mapping
|
||||
|
||||
### Chat (`ChatClient` / `AsyncChatClient`)
|
||||
|
||||
| SDK method | HTTP | Notes |
|
||||
|------------|------|--------|
|
||||
| `create_chat_completion` | `POST /api/v1/chat/completions` | `stream=True` for SSE; optional `chatId`, `variables`, `detail` |
|
||||
| `get_chat_histories` | `POST /api/core/chat/getHistories` | Requires `appId` |
|
||||
| `get_chat_init` | `GET /api/core/chat/init` | |
|
||||
| `get_chat_records` | `POST /api/core/chat/getPaginationRecords` | |
|
||||
| `get_record_detail` | `GET /api/core/chat/getResData` | |
|
||||
| `update_chat_history` | `POST /api/core/chat/updateHistory` | |
|
||||
| `delete_chat_history` | `DELETE /api/core/chat/delHistory` | |
|
||||
| `clear_chat_histories` | `DELETE /api/core/chat/clearHistories` | |
|
||||
| `delete_chat_record` | `DELETE /api/core/chat/item/delete` | |
|
||||
| `send_feedback` | `POST /api/core/chat/feedback/updateUserFeedback` | |
|
||||
| `get_suggested_questions` | `POST /api/core/ai/agent/v2/createQuestionGuide` | |
|
||||
|
||||
### App / 应用管理 (`AppClient` / `AsyncAppClient`)
|
||||
|
||||
| SDK method | HTTP | OpenAPI tag |
|
||||
|------------|------|-------------|
|
||||
| `get_app_logs_chart` | `POST /api/proApi/core/app/logs/getChartData` | 应用管理 — log dashboard |
|
||||
|
||||
**Not implemented in SDK yet** (see official app docs): e.g. `GET /api/proApi/core/app/logs/getTotalData`. Add methods in `client.py` and `async_client.py`, mirror in tests, and document in `docs/api/app_client.md`.
|
||||
|
||||
## Conventions for changes
|
||||
|
||||
1. **Match existing style:** Google docstrings, type hints on public APIs, camelCase parameter names where the API uses them (`appId`, `chatId`, `dateStart`).
|
||||
2. **Responses:** Methods return `httpx.Response`; callers use `.raise_for_status()` and `.json()`. Map HTTP errors via `fastgpt_client.exceptions` in `_handle_error_response`.
|
||||
3. **Sync + async:** Implement both when adding a new endpoint.
|
||||
4. **Tests:** Add/update tests under `tests/test_*_client.py`; run `pytest` before finishing.
|
||||
5. **Docs:** Update `docs/api/*.md` and `README.md` only when behavior or public API changes.
|
||||
6. **Scope:** Minimal diffs; no unrelated refactors. Do not commit secrets (`.env`, API keys).
|
||||
|
||||
## Typical usage (for generated code)
|
||||
|
||||
```python
|
||||
from fastgpt_client import ChatClient, AppClient
|
||||
|
||||
with ChatClient(api_key="fastgpt-...", base_url="https://cloud.fastgpt.cn") as chat:
|
||||
r = chat.create_chat_completion(
|
||||
messages=[{"role": "user", "content": "Hello"}],
|
||||
stream=False,
|
||||
)
|
||||
r.raise_for_status()
|
||||
print(r.json()["choices"][0]["message"]["content"])
|
||||
|
||||
with AppClient(api_key="fastgpt-...", base_url="https://cloud.fastgpt.cn") as app:
|
||||
r = app.get_app_logs_chart(
|
||||
appId="your-app-id",
|
||||
dateStart="2025-01-01T00:00:00.000Z",
|
||||
dateEnd="2025-01-31T23:59:59.999Z",
|
||||
source=["api", "online"],
|
||||
)
|
||||
r.raise_for_status()
|
||||
```
|
||||
|
||||
Streaming: prefer `iter_stream_events` / `aiter_stream_events` over hand-parsing SSE when possible (see `docs/advanced/streaming_events.md`).
|
||||
|
||||
## Development commands
|
||||
|
||||
```bash
|
||||
pip install -e ".[dev]"
|
||||
pytest
|
||||
ruff check fastgpt_client/
|
||||
ruff format fastgpt_client/
|
||||
mkdocs serve # optional: local docs
|
||||
```
|
||||
|
||||
## When unsure
|
||||
|
||||
1. Read the matching method in `fastgpt_client/client.py`.
|
||||
2. Cross-check the [cloud OpenAPI](https://cloud.fastgpt.cn/openapi) or [doc.fastgpt.io](https://doc.fastgpt.io/) for request/response shapes.
|
||||
3. Follow patterns in `tests/` and `examples/`.
|
||||
Reference in New Issue
Block a user