使用说明

🚀 API查特勒姆

作者： Weslley da Costa Sebastião

这个API组织自定义代理的生命周期（注册和运行），允许他们访问本地托管在项目中的工具（通过文件夹）。 src/mcp/tools）或可选的外部 MCP 服务器。

该服务充当LLM代理人的编排中心。它简化了整个周期的管理，从注册和管理代理到最终执行，包括对话内存和使用遥测。该项目还包括一个管道 自动代码审查 用于提取请求（PR）和用于指标分析的仪表板端点。

📌 摘要

概述
主要功能
架构与流程
文件夹结构
要求
配置（.env）
安装和运行
API 文档
MCP 工具
遥测与记忆
常见问题

🧭 概述

ChatLLM API提供：

代理人 带有提示符，模板和允许的工具列表。
执行代理 具有对话记忆和成本/使用跟踪功能。
与 MCP 集成 （本地通过文件或外部服务器）。
管道审查与公关执行自动分析并在银行记录结果。
仪表板端点 用于指标和报告。

✨ 主要功能

代理人管理 （创建和列表）
使用 LangChain + LangGraph 执行代理.
可扩展工具 通过 src/mcp/tools/*.
Supabase 数据库（Postgres） 为了坚持。
对话记忆 每个会话。
成本遥测和令牌 通过执行。
自动审查拉动请求 历史和统计。

🏗️ 架构与流程

1）注册代理人

O端点 POST /agent 将代理配置保存到银行（Supabase）。

2）执行

O端点 POST /agent/run/v2:
1. 载入代理配置。
2. 载入允许的工具。
3. 使用LangChain运行代理。
4. 记录遥测，令牌和成本。

3） PR评论

O端点 POST /api/v1/reviews/pr/run:
- 需要用户验证 Authorization: Bearer e标题 X-GitHub-Token.
- 运行审查管道并返回最终报告。

🗂️ 文件夹结构

.
├── main.py                     # Ponto de entrada FastAPI
├── README.md
├── requirements.txt
└── src
    ├── api                      # Rotas HTTP
    │   ├── routes.py            # Agentes + health + list_tools
    │   ├── DashboardViews       # Endpoints do dashboard
    │   └── reviews              # Endpoints de review de PR
    ├── core                     # Configuração e logging
    ├── data                     # Persistência (Supabase/Postgres)
    ├── mcp                      # Loader/registry e ferramentas locais
    ├── models                   # Schemas Pydantic
    ├── services                 # Lógicas de execução de agentes e reviews
    └── utils                    # Logs, helpers, telemetria

✅ 要求

Python 3.10+
Git
Supabase/Postgres 可访问 （为了坚持）
Chave OpenAI （LLM的执行）

⚙️ 配置（.env）

项目使用 pydantic-settings 通过加载环境变量 .env下面的变量是必需的：

APP_NAME="ChatLLM API"
APP_VERSION="0.6.0"
DEBUG=True

OPENAI_API_KEY="<defina-sua-chave-openai>"
MODEL_NAME="<modelo-padrão>"
FRONT_URL="http://localhost:3000"
API_KEY="<defina-uma-chave-segura>"

SUPABASE_DB_USER="<usuario>"
SUPABASE_DB_PASSWORD="<senha>"
SUPABASE_DB_HOST="<host>"
SUPABASE_DB_PORT=5432
SUPABASE_DB_NAME="<database>"

ℹ️ 注释

MODEL_NAME 在应用程序中用作备份/默认值。

API_KEY 保护或结束PR审查。

在仓库中没有真正的版本凭据；使用一个 .env 位置或环境变量。

▶️ 安装和运行

克隆仓库

git clone [URL_DO_SEU_REPOSITORIO]
cd [NOME_DA_PASTA_DO_PROJETO]

创建虚拟环境

python3 -m venv venv
source venv/bin/activate

安装依赖关系

pip install -r requirements.txt

配置o .env （如上所示）
启动应用程序

uvicorn main:app --host 0.0.0.0 --port 8080 --reload

该应用程序将在： http://localhost:8080

📖 API 文档

交互式文档（Swagger）位于：

http://localhost:8080/docs

替代文档（ReDoc）：

http://localhost:8080/redoc

主要端点

✅ 健康检查

获取 /health

答案：

{
  "status": "ok"
}

📌 创建代理

发布 /agent

主体：

{
  "name": "Agente Suporte",
  "description": "Atende clientes",
  "provider": "openai",
  "model": "gpt-4o-mini",
  "prompt": "Você é um atendente virtual...",
  "temperature": 0.7,
  "max_tokens": 1024,
  "tools": ["hello_world"]
}

答案：

{
  "message": "Agente criado com sucesso",
  "agent_id": "uuid"
}

📌 列出代理

获取 /agent

答案（例子）：

[
  {
    "id": "uuid",
    "name": "Agente Suporte"
  }
]

▶️ 运行代理（推荐）

发布 /agent/run/v2

主体：

{
  "agent_id": "uuid",
  "user_id": "usuario-123",
  "session_id": null,
  "message": "Qual o status do meu pedido?"
}

答案：

{
  "response": "Resposta do agente...",
  "session_id": "uuid-session"
}

⚠️ 运行代理（传统）

发布 /agent/run

此终端当前接受方案 AgentRunRequest (user_prompt, id但内部委托给运行时 v2。建议使用 /agent/run/v2 为了避免不兼容。

🧰 列出可用的工具

获取 /list_tools

答案：

{
  "tools": [
    {
      "name": "hello_world"
    }
  ]
}

仪表板端点

前缀： /dashboard

获取 `/dashboard/overview`

返回带有可选过滤器的概览（总计） agent_id.

获取 `/dashboard/totals-by-agent`

返回按代理添加的指标。

获取 `/dashboard/last-runs`

列出最近执行时间。参数：

limit (1–200)
agent_id （可选）
status （可选）

PR审查的终点

前缀： /api/v1/reviews

▶️ Rodar审查公关

发布 /api/v1/reviews/pr/run

必需的标题：

Authorization: Bearer <API_KEY>
X-GitHub-Token: <TOKEN_GITHUB>

主体：

{
  "repo_full_name": "WeslleySebastiao/chatllm-api",
  "pr_number": 12,
  "head_sha": "abc123",
  "base_sha": "def456"
}

答案：

{
  "repo_full_name": "WeslleySebastiao/chatllm-api",
  "pr_number": 12,
  "result": {}
}

🔎 最新PR评论

获取 /api/v1/reviews/pr/latest

查询：

repo_full_name
pr_number

🔎 按作业审查

获取 /api/v1/reviews/jobs/{job_id}

📜 PR历史回顾

获取 /api/v1/reviews/pr/history

查询：

repo_full_name
pr_number
limit (1–100)
offset

📚 已分析的仓库

获取 /api/v1/reviews/repos

📂 PRS分析师DOS

获取 /api/v1/reviews/prs

查询：

repo_full_name
limit (1–200)
offset

🧩 MCP 工具

本地工具在：

src/mcp/tools/<nome_da_ferramenta>/
├── function.py
└── schema.json

启动服务器时，加载器会自动记录该文件夹中找到的所有工具。要添加新工具：

用工具名称创建文件夹。
添加 function.py 与主要功能。
添加 schema.json com description e parameters.

📊 遥测与记忆

遥测每次执行记录时间，令牌和成本（通过 utils/log.py).
对话记忆会话在银行中保留，以允许来自同一用户的呼叫之间的上下文。

🧯 常见问题

Erro 401无终点复查检查是否 API_KEY 不 .env 这是正确的。
与银行连接错误: 验证 Supabase 凭据。
执行代理程式时发生错误：确认 OPENAI_API_KEY 是否有效，模型是否存在。