# ai-agent-server

**Repository Path**: ai-agent-study/ai-agent-server

## Basic Information

- **Project Name**: ai-agent-server
- **Description**: 基于Python的学习项目。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-29
- **Last Updated**: 2026-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Server Lab 智能体服务学习项目

`agent-server-lab` 是一个用于学习 AI 智能体服务端工作原理的小型 Python 项目。项目刻意不引入智能体编排框架，让模型、工具、检索、会话状态与 HTTP API 之间的边界清晰可见。

默认的 `LearningModel` 可以离线运行：输入 `search <查询内容>` 会触发知识检索，包含 `time` 的问题会触发时间工具。准备接入真实模型时，可切换到 OpenAI-compatible 接口。

## 零依赖启动

默认服务只使用 Python 标准库和离线教学模型：

```bash
cd /Users/qimao/work/ai/agent-server-lab
PYTHONPATH=src python3 -m agent_server.stdlib_server
```

服务监听 `http://127.0.0.1:8000`，提供下文相同的 `/health` 与 `/v1/chat` API。

## 升级到 FastAPI

网络可用时，安装依赖即可使用 OpenAPI 文档和 FastAPI 传输层：

```bash
cd /Users/qimao/work/ai/agent-server-lab
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
uvicorn agent_server.main:app --reload
```

OpenAPI 页面地址为 `http://127.0.0.1:8000/docs`。

```bash
curl http://127.0.0.1:8000/health

curl -X POST http://127.0.0.1:8000/v1/chat \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"learn-1","message":"search agent loop"}'
```

## 切换到真实模型

在 shell 环境中加载 `.env.example` 的变量。目标供应商必须实现 OpenAI-compatible 的 `POST /v1/chat/completions` 接口并支持函数工具调用；该模式使用 FastAPI 启动入口。

```bash
export MODEL_BACKEND=openai
export MODEL_BASE_URL=https://your-provider.example/v1
export MODEL_API_KEY=replace-me
export MODEL_NAME=replace-me
uvicorn agent_server.main:app --reload
```

不要提交真实 API Key。内置适配器只服务于单工具闭环学习；公开部署前请阅读[技术入门文档](docs/python-ai-agent-server-quickstart.md)。

## 推荐阅读顺序

1. `src/agent_server/tools.py`：工具白名单与输入校验。
2. `src/agent_server/agent.py`：有步骤上限的模型-工具循环。
3. `src/agent_server/retrieval.py`：本地 RAG 数据路径。
4. `src/agent_server/api.py`：FastAPI 接口契约与错误映射。
5. `docs/python-ai-agent-server-quickstart.md`：从基础到生产化的知识体系。

## 测试

```bash
PYTHONPATH=src python3 -m unittest discover -s tests -v
```

## 教学边界

项目使用内存会话与词元重叠检索，以便阅读核心机制。生产服务还需要持久化状态、向量检索、租户隔离、鉴权、限流、可观测性、评估与工作队列；对应的演进路线见技术文档。