版本: v2.0.0
更新日期: 2025-10-27
API类型: REST API
基础URL: http://localhost:8080
http://localhost:8080/swagger-ui
# 健康检查
curl http://localhost:8080/health
# 添加记忆
curl -X POST http://localhost:8080/api/v1/memories \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent-123",
"content": "用户喜欢披萨",
"importance": 0.8
}'
# 搜索记忆
curl -X POST http://localhost:8080/api/v1/memories/search \
-H "Content-Type: application/json" \
-d '{
"query": "用户喜欢什么",
"agent_id": "agent-123",
"limit": 10
}'Authorization: Bearer <your-jwt-token>curl -X POST http://localhost:8080/api/v1/users/login \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "your-password"
}'响应:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "user-123",
"email": "user@example.com"
}
}POST /api/v1/memories
请求体:
{
"agent_id": "agent-123",
"user_id": "user-456",
"content": "用户在2023年访问过巴黎",
"memory_type": "episodic",
"importance": 0.8,
"metadata": {
"location": "Paris",
"year": "2023"
}
}响应 (200 OK):
{
"id": "mem-789",
"message": "Memory added successfully"
}GET /api/v1/memories/{id}
响应 (200 OK):
{
"id": "mem-789",
"agent_id": "agent-123",
"content": "用户在2023年访问过巴黎",
"memory_type": "episodic",
"importance": 0.8,
"metadata": {
"location": "Paris",
"year": "2023"
},
"created_at": "2023-10-27T12:00:00Z",
"updated_at": "2023-10-27T12:00:00Z"
}PUT /api/v1/memories/{id}
请求体:
{
"content": "用户在2023年夏天访问过巴黎",
"importance": 0.9
}DELETE /api/v1/memories/{id}
响应 (200 OK):
{
"id": "mem-789",
"message": "Memory deleted successfully"
}POST /api/v1/memories/search
请求体:
{
"query": "用户去过哪里旅行",
"agent_id": "agent-123",
"memory_type": "episodic",
"limit": 10,
"threshold": 0.7
}响应 (200 OK):
{
"results": [
{
"id": "mem-789",
"content": "用户在2023年访问过巴黎",
"similarity": 0.95,
"importance": 0.8
}
],
"total": 1
}POST /api/v1/memories/batch
请求体:
{
"memories": [
{
"agent_id": "agent-123",
"content": "记忆1",
"importance": 0.7
},
{
"agent_id": "agent-123",
"content": "记忆2",
"importance": 0.8
}
]
}响应 (200 OK):
{
"successful": 2,
"failed": 0,
"results": [
{"id": "mem-001", "message": "Success"},
{"id": "mem-002", "message": "Success"}
],
"errors": []
}GET /api/v1/agents/{agent_id}/memories
响应 (200 OK):
{
"memories": [
{
"id": "mem-001",
"content": "记忆内容",
"importance": 0.8
}
],
"total": 1
}POST /api/v1/agents
请求体:
{
"organization_id": "org-123",
"name": "Customer Support Bot",
"description": "处理客户咨询的智能助手"
}响应 (200 OK):
{
"id": "agent-456",
"organization_id": "org-123",
"name": "Customer Support Bot",
"state": "active",
"created_at": "2023-10-27T12:00:00Z"
}GET /api/v1/agents/{id}
PUT /api/v1/agents/{id}
请求体:
{
"name": "Updated Bot Name",
"description": "Updated description"
}DELETE /api/v1/agents/{id}
GET /api/v1/agents
查询参数:
limit: 返回数量(默认50)offset: 偏移量(默认0)
响应 (200 OK):
{
"agents": [
{
"id": "agent-001",
"name": "Bot 1",
"state": "active"
}
],
"total": 1
}GET /api/v1/agents/{agent_id}/state
响应 (200 OK):
{
"agent_id": "agent-123",
"state": "active",
"last_active_at": "2023-10-27T12:00:00Z",
"memory_count": 150,
"error_message": null
}PUT /api/v1/agents/{agent_id}/state
请求体:
{
"state": "idle",
"error_message": null
}POST /api/v1/agents/{agent_id}/chat
请求体:
{
"message": "你好,我需要帮助",
"context": {
"user_id": "user-123",
"session_id": "session-456"
}
}响应 (200 OK):
{
"response": "你好!我是你的智能助手,很高兴为你服务。请问有什么可以帮到你的?",
"agent_id": "agent-123",
"timestamp": "2023-10-27T12:00:00Z",
"tool_calls": []
}POST /api/v1/agents/{agent_id}/chat/stream
响应: Server-Sent Events (SSE)
// JavaScript示例
const eventSource = new EventSource('/api/v1/agents/agent-123/chat/stream');
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log(data.chunk); // 流式内容
};GET /api/v1/agents/{agent_id}/chat/history
查询参数:
limit: 返回数量(默认50)before: 时间戳,获取之前的消息
响应 (200 OK):
{
"messages": [
{
"role": "user",
"content": "你好",
"timestamp": "2023-10-27T12:00:00Z"
},
{
"role": "assistant",
"content": "你好!有什么可以帮你?",
"timestamp": "2023-10-27T12:00:01Z"
}
],
"total": 2
}POST /api/v1/users/register
请求体:
{
"email": "user@example.com",
"password": "SecurePassword123!",
"full_name": "张三"
}响应 (200 OK):
{
"id": "user-123",
"email": "user@example.com",
"full_name": "张三",
"created_at": "2023-10-27T12:00:00Z"
}POST /api/v1/users/login
请求体:
{
"email": "user@example.com",
"password": "SecurePassword123!"
}响应 (200 OK):
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "user-123",
"email": "user@example.com"
},
"expires_at": "2023-10-28T12:00:00Z"
}GET /api/v1/users/me
Headers: Authorization: Bearer <token>
PUT /api/v1/users/me
请求体:
{
"full_name": "李四",
"avatar_url": "https://example.com/avatar.jpg"
}POST /api/v1/users/me/password
请求体:
{
"old_password": "OldPassword123!",
"new_password": "NewPassword123!"
}POST /api/v1/organizations
请求体:
{
"name": "Acme Corp",
"description": "我们的智能助手平台"
}GET /api/v1/organizations/{org_id}
PUT /api/v1/organizations/{org_id}
DELETE /api/v1/organizations/{org_id}
GET /api/v1/organizations/{org_id}/members
GET /health
响应 (200 OK):
{
"status": "healthy",
"timestamp": "2023-10-27T12:00:00Z",
"version": "2.0.0",
"checks": {
"database": {
"status": "healthy",
"message": "Database connection successful",
"last_check": "2023-10-27T12:00:00Z"
},
"memory_system": {
"status": "healthy",
"message": "Memory system operational",
"last_check": "2023-10-27T12:00:00Z"
}
}
}GET /health/live
响应 (200 OK):
{
"status": "alive",
"timestamp": "2023-10-27T12:00:00Z",
"version": "2.0.0"
}GET /health/ready
响应 (200 OK / 503 Service Unavailable):
{
"status": "ready",
"timestamp": "2023-10-27T12:00:00Z",
"checks": {
"database": true,
"memory_system": true
}
}{
"code": "RESOURCE_NOT_FOUND",
"message": "Memory with id 'mem-123' not found",
"details": {
"resource_type": "memory",
"resource_id": "mem-123"
},
"timestamp": "2023-10-27T12:00:00Z"
}| 状态码 | 说明 | 示例 |
|---|---|---|
| 200 | 成功 | 请求成功处理 |
| 201 | 已创建 | 资源创建成功 |
| 400 | 请求错误 | 参数验证失败 |
| 401 | 未授权 | Token无效或过期 |
| 403 | 禁止访问 | 权限不足 |
| 404 | 未找到 | 资源不存在 |
| 409 | 冲突 | 资源已存在 |
| 422 | 无法处理 | 语义错误 |
| 429 | 请求过多 | 速率限制 |
| 500 | 服务器错误 | 内部错误 |
| 503 | 服务不可用 | 维护中 |
| 错误代码 | HTTP状态 | 说明 |
|---|---|---|
INVALID_REQUEST |
400 | 请求参数无效 |
UNAUTHORIZED |
401 | 未授权访问 |
FORBIDDEN |
403 | 权限不足 |
RESOURCE_NOT_FOUND |
404 | 资源未找到 |
RESOURCE_CONFLICT |
409 | 资源冲突 |
VALIDATION_ERROR |
422 | 验证失败 |
RATE_LIMIT_EXCEEDED |
429 | 超过速率限制 |
INTERNAL_ERROR |
500 | 服务器内部错误 |
SERVICE_UNAVAILABLE |
503 | 服务不可用 |
import requests
# 基础配置
BASE_URL = "http://localhost:8080"
TOKEN = "your-jwt-token"
headers = {
"Authorization": f"Bearer {TOKEN}",
"Content-Type": "application/json"
}
# 添加记忆
response = requests.post(
f"{BASE_URL}/api/v1/memories",
headers=headers,
json={
"agent_id": "agent-123",
"content": "用户喜欢披萨",
"importance": 0.8
}
)
print(response.json())
# 搜索记忆
response = requests.post(
f"{BASE_URL}/api/v1/memories/search",
headers=headers,
json={
"query": "用户喜欢什么",
"agent_id": "agent-123",
"limit": 10
}
)
print(response.json())const BASE_URL = 'http://localhost:8080';
const TOKEN = 'your-jwt-token';
const headers = {
'Authorization': `Bearer ${TOKEN}`,
'Content-Type': 'application/json'
};
// 添加记忆
const addMemory = async () => {
const response = await fetch(`${BASE_URL}/api/v1/memories`, {
method: 'POST',
headers,
body: JSON.stringify({
agent_id: 'agent-123',
content: '用户喜欢披萨',
importance: 0.8
})
});
return await response.json();
};
// 搜索记忆
const searchMemories = async () => {
const response = await fetch(`${BASE_URL}/api/v1/memories/search`, {
method: 'POST',
headers,
body: JSON.stringify({
query: '用户喜欢什么',
agent_id: 'agent-123',
limit: 10
})
});
return await response.json();
};# 设置变量
export BASE_URL="http://localhost:8080"
export TOKEN="your-jwt-token"
# 添加记忆
curl -X POST "$BASE_URL/api/v1/memories" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent-123",
"content": "用户喜欢披萨",
"importance": 0.8
}'
# 搜索记忆
curl -X POST "$BASE_URL/api/v1/memories/search" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"query": "用户喜欢什么",
"agent_id": "agent-123",
"limit": 10
}'| 端点类型 | 限制 | 时间窗口 |
|---|---|---|
| 读取操作 | 1000请求 | 1分钟 |
| 写入操作 | 100请求 | 1分钟 |
| 搜索操作 | 500请求 | 1分钟 |
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1635350400{
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Try again in 60 seconds.",
"retry_after": 60
}- Swagger UI: http://localhost:8080/swagger-ui
- OpenAPI JSON: http://localhost:8080/api-docs/openapi.json
- 健康检查: http://localhost:8080/health
- Metrics: http://localhost:8080/metrics/prometheus
文档版本: v2.0.0
最后更新: 2025-10-27
维护团队: AgentMem API Team