一句话：把 AI Agent 的规划、工具调用、检索、反思与评测过程，变成可观察、可调试的事件流。
TypeScript · React · Node.js · Zustand · SSE · npm workspaces ｜ LLM 接入 OpenAI 兼容模型（未配置 Key 时 Mock 回退）｜ RAG 为关键词检索，详见 Implementation Notes
本地 demo 的真实录屏：从 idle 一次 Run full demo 跑到 success，包含事件速率曲线、依赖图和 Timeline 切换。
Agent 执行是黑盒：调了哪个工具、检索到什么、为什么失败，都看不到。 这个项目用 Runtime Event 记录全过程，并投影到 Chat / Graph / Timeline / Inspector 四个同步视图； 一次演示任务会走完 Planning → Tool Call → Knowledge Retrieval → Memory Update → Reflection → Evaluation → Final Answer。
Agent Studio turns a running AI agent into a runtime console: four synchronized views (Chat / Graph / Timeline / Inspector) projected from a single runtime state model. It is not a ChatGPT clone, not a dashboard template, and not a fake SaaS shell.
The main demo starts with:
分析华东区域销售下降原因，并生成报告
The runtime then moves through:
Planning -> Tool Call -> Knowledge Retrieval -> Memory Update -> Reflection -> Evaluation -> Final Answer
The /agent page is the product center. Chat is the primary workspace. Graph explains runtime dependency. Timeline debugs event flow. Inspector and Drawer explain the selected RuntimeObject.
- Agent Runtime lifecycle: Planner, WorkflowRunner, ToolExecutor, RAG, Memory, Reflection, Evaluation, and Final Answer.
- Real Runtime Server: task creation, task query, cancel, retry, and SSE event streaming.
- RuntimeObject model: one projected object model shared by Chat, Graph, Timeline, Inspector, Drawer, Evidence, Memory, and Evaluation.
- Execution Graph: compact dependency graph for Planner, Workflow, Tool, Knowledge, Memory, Reflection, Evaluation, and Answer.
- Debug Timeline: runtime spans with component, status, duration, retry, token, metadata, input, and output.
- Professional Inspector: object-driven panels for execution, input, output, reasoning, trace, evidence, memory, evaluation, and logs.
- Demo path: one-click demo task plus failure recovery demo for Tool Error -> Retry -> Reflection -> Success.
flowchart TD
A[React Agent Console] -->|POST /api/agent/tasks| B[Runtime Server]
A -->|EventSource SSE| B
B --> C[TaskManager]
C --> D[Agent Runtime]
D --> E[Planner]
E --> F[WorkflowRunner]
F --> G[ToolExecutor + ToolRegistry]
F --> H[RAG Retriever + Knowledge Base]
F --> I[Memory Manager]
F --> J[Reflection]
J --> K[Evaluator]
K --> L[Final Answer]
D --> M[Trace + Metrics]
B -->|runtime events| A
A --> N[RuntimeObject Projection]
N --> O[Chat + Graph + Timeline + Inspector + Drawer]
User Goal
-> createAgentTask(input)
-> Runtime Server creates task
-> Agent Runtime emits events
-> SSE streams AgentServerEvent
-> Zustand updates session state
-> RuntimeObject projection
-> Chat / Graph / Timeline / Inspector / Drawer synchronize
Supported events include:
task_created
plan_start
plan_update
tool_start
tool_success
tool_error
task_retry
rag_retrieve
memory_update
reflection
evaluation_start
evaluation_complete
state_update
final_answer
task_complete
Screenshots are captured from the same local demo task (the recording above is the moving version):
分析华东区域销售下降原因，并生成报告
The seven frames below follow one runtime session from idle to evaluation. They are intentionally shown as full-width frames so the runtime behavior remains legible on the GitHub project page.
Ready state before the task starts: quick demo entry, runtime path, and the initial Inspector context.
The sales decline task is active and the console follows the current RuntimeObject.
ToolExecutor calls sales-data and metric tools while Chat, Graph, Timeline, and Inspector update together.
RAG retrieves evidence for the East China sales decline causes and exposes source chunks.
The Timeline shows runtime spans, duration, component, status, retry, token, and trace context.
The selected Final Answer object exposes output, evidence, dependencies, and trace spans.
Evaluation Center shows score, criteria, feedback, and quality review for the completed sales task.
| Layer | Technology |
|---|---|
| Frontend | React, TypeScript, Vite, React Router |
| State | Zustand |
| UI | Tailwind CSS, Framer Motion, local design tokens |
| Server | Node.js HTTP server, TypeScript |
| Streaming | Server-Sent Events |
| Runtime | Planner, WorkflowRunner, ToolExecutor, RAG, Memory, Reflection, Evaluation |
| Shared Contracts | TypeScript shared-types package |
The project documentation is organized by responsibility:
- Product: positioning, users, information architecture, and roadmap context.
- Design: visual principles and Runtime Workspace direction.
- UX: navigation, interaction, and runtime state transitions.
- Design System: shared tokens and component rules.
- Architecture: frontend, server, runtime, and streaming boundaries.
- Demo Scripts: 3-minute, 10-minute, and 30-minute walkthroughs.
- Contributing: development flow and verification commands.
- Performance: telemetry cost, bundle split, and how to reproduce.
- Changelog: implementation history.
apps/
├── agent-console/
│ └── src/
│ ├── components/
│ ├── features/agent-console/
│ ├── hooks/
│ ├── layout/
│ ├── pages/
│ ├── router/
│ ├── services/
│ ├── store/
│ ├── theme/
│ └── types/
└── runtime-server/
└── src/
├── runtime/
├── sse/
└── task/
packages/
├── agent-runtime/
│ └── src/
│ ├── agent/
│ ├── evaluation/
│ ├── llm/
│ ├── memory/
│ ├── observability/
│ ├── planner/
│ ├── rag/
│ ├── tool/
│ └── workflow/
├── shared-types/
└── shared-utils/
docs/
├── PRODUCT.md
├── DESIGN.md
├── UX.md
├── DESIGN_SYSTEM.md
├── ARCHITECTURE.md
├── ROADMAP.md
├── DEMO_SCRIPT.md
├── screenshots/
└── media/
默认是无 key 的 Mock 模式（输入框下方会显示 MOCK 徽标，回答由本地模板生成）。接真实模型三步：
cp .env.example .env # .env 已被 git-ignore
# 编辑 .env，填入 DEEPSEEK_API_KEY=...
npm run server服务端按顺序解析：
| 优先级 | 变量 | 默认值 |
|---|---|---|
| 1 | DEEPSEEK_API_KEY |
baseURL https://api.deepseek.com/v1，model deepseek-chat |
| 2 | OPENAI_API_KEY |
baseURL https://api.openai.com/v1，model gpt-4.1-mini |
| 3 | 都没有 | Mock 模式 |
GET /health 返回当前实际 provider（deepseek / openai / mock），控制台的 MOCK 徽标就依据它显示。
.env、.env.*都在.gitignore里，仓库里只有空占位的.env.example。npm test的第一步是node scripts/check-secrets.mjs：扫描所有 git 跟踪的文件，命中sk-形状或非空的*_API_KEY=直接失败退出。- 单独检查：
npm run check:secrets。 - 万一提交过：先去平台吊销这个 key，再清理历史（
git filter-repo）。只删文件不够，历史里还在。
未配置
OPENAI_API_KEY时服务端运行在 Mock 模式：界面底部会显示Mock标记，回答来自本地模板而不是模型调用。想看完整脚本化链路，请提问「分析华东区域销售下降原因，并生成报告」。
Install dependencies:
npm installOptional: copy the frontend environment template if you want to customize local settings.
cp apps/agent-console/.env.example apps/agent-console/.envStart the Runtime Server:
npm run serverStart the React Console in another terminal:
npm --prefix apps/agent-console run devOr start both processes with one command:
npm run dev:allOpen:
http://127.0.0.1:5173/agent
The Runtime Server health endpoint is:
http://127.0.0.1:3001/health
Frontend environment:
apps/agent-console/.env.example
VITE_AGENT_SERVER_URL=http://127.0.0.1:3001
Primary demo task:
分析华东区域销售下降原因，并生成报告
Expected demo sequence:
1. Chat receives the business goal.
2. Planner creates executable steps.
3. ToolExecutor queries sales data and calculates metrics.
4. RAG retrieves relevant knowledge chunks.
5. Memory stores working / episodic / semantic context.
6. Reflection checks whether the answer is complete.
7. Evaluation scores completeness, accuracy, groundedness, and task completion.
8. Final Answer streams into Chat as Markdown.
9. Graph, Timeline, Inspector, Drawer, Evidence, Memory, and Evaluation stay synchronized.
Demo scripts:
npm run lint
npm run test
npm run buildNote: in restricted sandbox environments, tsx and Vite may fail with local IPC or port-listening errors such as listen EPERM ... tsx-501/*.pipe. Run the same commands in a normal local terminal for final verification.
The test suite covers RuntimeObject projection, SSE event projection, Knowledge and Memory derived views, Timeline modeling, Inspector rendering, and the Runtime Server health endpoint.
- Frame-gated telemetry. Event ingestion is incremental; the chart paints at most once per animation frame and pauses when the tab is hidden.
- Bounded memory. A capped 60-bucket ring buffer keeps per-frame cost flat as the session grows, instead of rescanning the full event array.
- Code-split chart. ECharts ships in its own lazy chunk, so the console's first-screen chunk stays at 200 kB (56 kB gzip) instead of 699 kB (226 kB gzip).
Numbers, method and limitations: docs/PERFORMANCE.md. Reproduce with npx tsx scripts/bench-event-rate.ts.
本节说明各能力的实现方式与当前范围。
LLM 层是可替换的抽象（packages/agent-runtime/src/llm/provider.ts）：
export interface LLMProvider {
name: string
chat(messages: ChatMessage[], tools?: ToolDefinition[]): Promise<LLMResponse>
}OpenAIProvider（llm/openai-provider.ts，143 行）实现真实模型调用：
- 真实
fetch请求${baseURL}/chat/completions，携带Authorization: Bearer ${apiKey} - 默认
baseURL = https://api.openai.com/v1，model = gpt-4.1-mini - 解析
choices[0].message与tool_calls（含function.name/function.arguments） - 对 HTTP 错误、空响应、tool call 字段缺失、参数解析失败做错误归一化
由于走的是 OpenAI 兼容协议，修改 baseURL 即可对接 DeepSeek / Qwen 等网关。
启用方式：
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.openai.com/v1 # 可替换为任意兼容网关
OPENAI_MODEL=gpt-4.1-miniMockLLMProvider（llm/mock-llm-provider.ts，99 行）用于离线演示与本地开发：
- 构造时注入一组预设响应队列，
chat()按index顺序返回 - 默认
delayMs = 200，模拟真实流式节奏 - 队列耗尽返回
{ content: 'No more responses.', done: true } - 选择逻辑（
agent/main.ts、apps/runtime-server/src/runtime/agent-runtime-adapter.ts）：
const realLLMProvider = process.env.OPENAI_API_KEY
? new OpenAIProvider({ apiKey, baseURL, model })
: undefined
const llmProvider = realLLMProvider ?? mockLLMProvider即：无 API Key 时整条 Agent 链路依然可以跑通，便于演示、CI 与本地开发。
当前是关键词检索，不是向量检索。
Retriever.retrieve(query, topK = 3)（rag/retriever.ts）的实际逻辑：
tokenize()：小写化 → 按中英文标点切分 → 中文额外做**二字滑窗（bigram）**切分- 打分：
score = matchedKeywords.length（命中关键词计数） - 过滤
score > 0→ 按 score 降序 → 取topK
本项目内没有 Embedding 模型、没有向量数据库、没有余弦相似度。
知识库内容为 createDefaultKnowledgeBase() 注入的内置示例文档（KnowledgeBase 是内存中的文档数组）。
项目 Settings 页面原文：
"Document ingestion and vector index management are future work."
向量检索与文档上传管线是明确的下一步计划，不是正在实现中的能力。
会话 id 由客户端持有并随每个任务发送（conversationId），服务端按它缓存一份 runtime bundle——planner hooks、memory、conversation history 都在里面。
- 追问会落到同一个
ConversationManager，上一轮的用户消息与助手回答会重新进入 prompt。 - 缓存上限 20 个会话，超出后按最早写入淘汰。
- prompt 只回放最近 24 条消息（system prompt 始终保留），避免长会话把 token 撑爆。
- 没带 id 的请求会自动新建会话，行为与之前一致。
monorepo 结构：apps/（agent-console、runtime-server）+ packages/（agent-runtime、shared-types、shared-utils）。
agent-runtime 的实际模块与导出：
| 模块 | 导出 |
|---|---|
agent/ |
Agent、ConversationManager、EventEmitter |
planner/ |
Planner、PlanValidator |
workflow/ |
WorkflowRunner、AgentState |
tool/ |
ToolRegistry、ToolExecutor（ToolTimeoutError / ToolArgumentError / ToolNotFoundError） |
rag/ |
Retriever、KnowledgeBase、ContextBuilder |
memory/ |
MemoryManager / MemoryUpdater / MemoryRetriever；Working / Episodic / Semantic 三层记忆 |
observability/ |
TraceManager、Span、AgentMetrics |
evaluation/ |
RuleBasedEvaluator |
runtime-server 负责任务生命周期（task-manager / task-store / task-repository）
与 SSE 事件流（sse/event-stream.ts），共 15 类运行时事件。
Implemented:
- TypeScript Agent Runtime
- Planner and PlanValidator
- WorkflowRunner
- ToolRegistry and ToolExecutor
- RAG retrieval over a local knowledge base
- Working / Episodic / Semantic memory model
- Reflection
- Evaluation
- Observability primitives
- Runtime Server with task lifecycle
- SSE event streaming
- Task cancel and retry
- React Runtime Studio
- RuntimeObject projection for Graph / Timeline / Inspector / Drawer
- Dashboard, Knowledge, Memory, Evaluation, Workflow, and Settings pages for demonstration
Not implemented intentionally:
- persistent vector database
- document upload pipeline
- persistent memory database
- historical evaluation datasets
- editable workflow deployment
- RBAC / SSO / audit logs
- secret management
- billing or team administration
These are roadmap items, not fake UI claims.
This project demonstrates:
- Frontend ability: React architecture, TypeScript, Zustand, SSE, design system, runtime workspace, graph, timeline, inspector, drawer, and interaction design.
- Agent ability: Planner, workflow execution, tool runtime, RAG, memory, reflection, evaluation, trace, and runtime events.
- Backend ability: task lifecycle, EventSource stream, Runtime Adapter, TaskManager, cancel/retry, and shared API contracts.
- Product judgment: runtime-first IA, honest boundaries, demo flow, and documentation that can be walked through out loud.
This is a personal project, built to work Agent Runtime engineering through end to end in the open; scope boundaries are listed in What Is Real Today.