|
| 1 | +# AI Agent API Documentation |
| 2 | + |
| 3 | +## Overview |
| 4 | +The AI Agent module provides a chat bot API that can answer questions about your blog content using AI. It supports both streaming and synchronous responses. |
| 5 | + |
| 6 | +## Configuration |
| 7 | +To enable the AI Agent, you need to configure the following in the admin panel: |
| 8 | + |
| 9 | +1. Go to Settings > AI Settings |
| 10 | +2. Set `openAiKey` - Your OpenAI API key |
| 11 | +3. Set `openAiEndpoint` (optional) - Custom OpenAI endpoint if needed |
| 12 | +4. Set `openAiPreferredModel` - Default: `gpt-4o-mini` |
| 13 | +5. Enable `enableAIAgent` - Toggle to enable the AI Agent feature |
| 14 | + |
| 15 | +## API Endpoints |
| 16 | + |
| 17 | +### POST `/api/ai/agent/chat` (Streaming) |
| 18 | +Chat with the AI agent about your blog content with streaming responses. |
| 19 | + |
| 20 | +**Authentication**: Required (must be logged in) |
| 21 | + |
| 22 | +**Request Body**: |
| 23 | +```json |
| 24 | +{ |
| 25 | + "message": "What are your latest blog posts?", |
| 26 | + "context": [ // Optional conversation history |
| 27 | + { |
| 28 | + "role": "user", |
| 29 | + "content": "Previous question" |
| 30 | + }, |
| 31 | + { |
| 32 | + "role": "assistant", |
| 33 | + "content": "Previous answer" |
| 34 | + } |
| 35 | + ] |
| 36 | +} |
| 37 | +``` |
| 38 | + |
| 39 | +**Response**: Server-Sent Events (SSE) stream |
| 40 | +``` |
| 41 | +data: {"type":"text","text":"Here are the latest blog posts"} |
| 42 | +data: {"type":"text","text":"..."} |
| 43 | +data: {"type":"finish","finishReason":"stop"} |
| 44 | +``` |
| 45 | + |
| 46 | +### POST `/api/ai/agent/chat/sync` (Non-Streaming) |
| 47 | +Chat with the AI agent synchronously (waits for complete response). |
| 48 | + |
| 49 | +**Authentication**: Required |
| 50 | + |
| 51 | +**Request Body**: Same as streaming endpoint |
| 52 | + |
| 53 | +**Response**: |
| 54 | +```json |
| 55 | +{ |
| 56 | + "message": "Here are the latest blog posts...", |
| 57 | + "timestamp": "2024-01-01T12:00:00.000Z" |
| 58 | +} |
| 59 | +``` |
| 60 | + |
| 61 | +### GET `/api/ai/agent/status` |
| 62 | +Check if the AI Agent is enabled and configured. |
| 63 | + |
| 64 | +**Authentication**: Required |
| 65 | + |
| 66 | +**Response**: |
| 67 | +```json |
| 68 | +{ |
| 69 | + "enabled": true, |
| 70 | + "service": "AI Agent Chat" |
| 71 | +} |
| 72 | +``` |
| 73 | + |
| 74 | +## Available Tools |
| 75 | +The AI Agent has access to the following tools to query your blog data: |
| 76 | + |
| 77 | +- **Posts**: Get posts by ID, list posts, get latest post, get posts by category/tag |
| 78 | +- **Notes**: Get notes by ID, list notes, get latest notes |
| 79 | +- **Categories**: Get category info, list all categories |
| 80 | +- **Tags**: Get tag summary, get posts by tag |
| 81 | +- **Pages**: Get page by ID, list all pages |
| 82 | +- **Says**: Get all says, get random say |
| 83 | +- **Recently**: Get recent activities |
| 84 | +- **Comments**: Get comments, get comments by content |
| 85 | + |
| 86 | +## Example Usage |
| 87 | + |
| 88 | +### Streaming Chat (JavaScript/TypeScript) |
| 89 | +```javascript |
| 90 | +const response = await fetch('http://localhost:2333/api/ai/agent/chat', { |
| 91 | + method: 'POST', |
| 92 | + headers: { |
| 93 | + 'Authorization': 'Bearer YOUR_TOKEN', |
| 94 | + 'Content-Type': 'application/json' |
| 95 | + }, |
| 96 | + body: JSON.stringify({ |
| 97 | + message: 'What blog posts do you have about TypeScript?' |
| 98 | + }) |
| 99 | +}) |
| 100 | + |
| 101 | +const reader = response.body.getReader() |
| 102 | +const decoder = new TextDecoder() |
| 103 | + |
| 104 | +while (true) { |
| 105 | + const { done, value } = await reader.read() |
| 106 | + if (done) break |
| 107 | + |
| 108 | + const text = decoder.decode(value) |
| 109 | + const lines = text.split('\n') |
| 110 | + |
| 111 | + for (const line of lines) { |
| 112 | + if (line.startsWith('data: ')) { |
| 113 | + const data = JSON.parse(line.slice(6)) |
| 114 | + if (data.type === 'text') { |
| 115 | + console.log(data.text) |
| 116 | + } |
| 117 | + } |
| 118 | + } |
| 119 | +} |
| 120 | +``` |
| 121 | + |
| 122 | +### Synchronous Chat |
| 123 | +```bash |
| 124 | +curl -X POST http://localhost:2333/api/ai/agent/chat/sync \ |
| 125 | + -H "Authorization: Bearer YOUR_TOKEN" \ |
| 126 | + -H "Content-Type: application/json" \ |
| 127 | + -d '{ |
| 128 | + "message": "What blog posts do you have about TypeScript?" |
| 129 | + }' |
| 130 | +``` |
| 131 | + |
| 132 | +### Check AI Agent Status |
| 133 | +```bash |
| 134 | +curl -X GET http://localhost:2333/api/ai/agent/status \ |
| 135 | + -H "Authorization: Bearer YOUR_TOKEN" |
| 136 | +``` |
| 137 | + |
| 138 | +## Streaming Response Format |
| 139 | +The streaming endpoint uses Server-Sent Events (SSE) format. Each message is prefixed with `data: ` and contains a JSON object: |
| 140 | + |
| 141 | +- `{"type":"text","text":"..."}` - Partial text response |
| 142 | +- `{"type":"tool-call","toolCall":{...}}` - Tool invocation information |
| 143 | +- `{"type":"tool-result","toolResult":{...}}` - Tool execution result |
| 144 | +- `{"type":"finish","finishReason":"stop"}` - Stream completion |
| 145 | + |
| 146 | +## Error Codes |
| 147 | +- `ErrorCodeEnum.AINotEnabled` - AI Agent is not enabled in the configuration |
| 148 | +- Authentication errors - User must be logged in to use the AI Agent |
0 commit comments