Skip to content

LiuYan-89937/FastAgentFactory

BranchesTags

Repository files navigation

FastAgentFactory

FastAgentFactory 是一个 CLI-first 的 Agent 工厂。它把自然语言需求整理成可编译、可运行、可测试、可扩展的 AgentPackage，并让工厂自身与生产出来的 Agent 尽量使用同一套运行规范。

项目的核心目标：

  • 用阶段化流程把需求转成 AgentPackage。
  • 用 RuntimeKernel 编译和运行 AgentPackage。
  • 用 RuntimeContracts 统一工具、记忆、知识、上下文、定时任务、Trace、Sandbox 等基础能力。
  • 用 TypeScript CLI 渲染工厂和子 Agent 的同一套事件流。
  • 让生成 Agent 默认在 Docker sandbox 中运行，避免宿主机环境污染。

架构概览

User
  -> TypeScript CLI
  -> Python JSONL Bridge
  -> Factory Host Workflows / AgentPackage Runtime
  -> RuntimeContracts
  -> RuntimeKernel
  -> Tools / Memory / Knowledge / Scheduler / Context / Trace
  -> Runtime Events
  -> CLI Render

工厂内置两条宿主侧工作流：

/chat         -> factory_chat AgentPackage
/create-agent -> host-side LangGraph ReAct manufacturing workflow

/create-agent 不再作为 RuntimeKernel SystemPackage 运行。它在独立制造工作区内通过 ReAct + todo + package validation 落地 AgentPackage；工具调用仍统一经过 ToolExecutionGateway。

生产出来的 AgentPackage 默认放在：

.agentfactory/packages/<factory_run_id>/

环境要求

  • Python 3.11+
  • Node.js / pnpm
  • uv
  • Docker Desktop 或可用 Docker daemon
  • OpenAI-compatible Chat Completions 模型服务
  • 可选：OpenAI-compatible embedding 模型服务

安装

安装 Python 依赖：

uv sync

安装 CLI 依赖：

pnpm --dir cli install

创建本地配置：

cp .env.example .env

基础配置

至少需要填写主模型：

AGENTFACTORY_OPENAI_BASE_URL=
AGENTFACTORY_OPENAI_API_KEY=
AGENTFACTORY_OPENAI_MODEL=

建议同时配置小任务模型、压缩模型和 embedding 模型：

AGENTFACTORY_TASK_MODEL=

AGENTFACTORY_COMPRESSION_BASE_URL=
AGENTFACTORY_COMPRESSION_API_KEY=
AGENTFACTORY_COMPRESSION_MODEL=

AGENTFACTORY_EMBEDDING_BASE_URL=
AGENTFACTORY_EMBEDDING_API_KEY=
AGENTFACTORY_EMBEDDING_MODEL=
AGENTFACTORY_EMBEDDING_DIMS=1536

常用运行配置：

AGENTFACTORY_SESSION_ROOT=.agentfactory/sessions
AGENTFACTORY_CHECKPOINTER_BACKEND=sqlite
AGENTFACTORY_CHECKPOINT_PATH=.agentfactory/checkpoints/factory.sqlite

AGENTFACTORY_MEMORY_STORE_BACKEND=sqlite
AGENTFACTORY_MEMORY_STORE_PATH=.agentfactory/memory/factory.sqlite
AGENTFACTORY_MEMORY_WRITE_INTERVAL_TURNS=3

AGENTFACTORY_TOOL_MAX_REVISIONS=5
AGENTFACTORY_TOOL_OUTPUT_MAX_MODEL_CHARS=12000

AGENTFACTORY_AGENT_RUNTIME_IDLE_TIMEOUT_SECONDS=1800
AGENTFACTORY_AGENT_RUNTIME_REQUEST_TIMEOUT_SECONDS=900

完整配置以 .env.example 为准。

启动

从仓库根目录启动 CLI：

pnpm factory

等价于：

pnpm --dir cli factory

CLI 会自动启动 Python bridge：

python -m agent_factory.factory_graph.frontend_bridge.stdio_server

正常使用时不需要手动启动 bridge。

CLI 常用命令

/chat
/create-agent
/run-agent-package
/agent-sessions
/sessions
/new-session
/resume <session_id>
/tools
/stages
/state on|off
/messages on|off
/tool-grep <query|off>
/stop <stage_id|off>
/exit
/quit
/help

说明：

  • /chat：进入工厂自由对话模式，可用于测试工具、记忆、知识库、定时任务等基础能力。
  • /create-agent：进入 Agent 生产入口；当前后端制造实现已清空，等待重新设计。
  • /run-agent-package：扫描 .agentfactory/packages，选择已生产 AgentPackage 并运行。
  • /agent-sessions：选择当前 AgentPackage 的会话。
  • /sessions：选择工厂会话。
  • /stop <stage_id|off>：设置或关闭生产流程阶段断点。
  • /tool-grep <query|off>：过滤工具活动展示。

Agent 生产入口

/create-agent 的 CLI 入口仍然保留。后端制造流程已经清空为占位 SystemPackage，新的生产链路确定后再接入。

AgentPackage 结构

一个 AgentPackage 的主要文件：

agent_package.json
assembly_spec.json
resources.json
sandbox_contract.json
render_manifest.json
package_report.json
contracts/
bindings/
prompts/
tools/
policies/
strategies/
formatters/

agent_package.json 只负责索引文件。运行能力由 contracts/*.json 声明，再由系统 Builder 注入 RuntimeKernel。

当前 AgentPackage 必须声明的 RuntimeContracts：

artifact
context
dependencies
knowledge
model
node_provider
render
resources
sandbox
scheduler
session
state
tools
trace

原则：

  • AssemblySpec 只描述 Agent 逻辑装配。
  • Runtime 基础设施不写进 AssemblySpec.metadata。
  • JSON 里不能声明自定义 Builder import path。
  • Builder 只能由系统注册。
  • 新增基础能力必须通过 contract、builder、contribution、package materialization 和编译校验接入。

子 Agent Docker 运行

普通 AgentPackage 默认通过 Docker sandbox 运行：

AgentPackage
  -> agentfactory-runtime-python:3.12
  -> sandbox init
  -> agent_runtime_bridge
  -> RuntimeKernel compile/run
  -> JSONL events
  -> CLI render

构建 runtime image：

docker build -t agentfactory-runtime-python:3.12 -f docker/agent-runtime/Dockerfile .

如果 Docker Hub 拉取基础镜像超时，可以指定镜像源：

docker build -t agentfactory-runtime-python:3.12 \
  --build-arg PYTHON_BASE_IMAGE=<python-3.12-slim-mirror> \
  -f docker/agent-runtime/Dockerfile .

sandbox 挂载约定：

/package                  read-only   AgentPackage
/resources/resources.json  read-only   resources.json
/artifacts                read-write  日志、报告、输出文件
/workdir                  read-write  临时工作区
/runtime                  read-write  session/checkpoint/memory/extensions/knowledge/trace
/runtime/extensions        read-write  用户后配置 MCP/Skill/扩展工具
/runtime/knowledge         read-write  用户后配置知识库
/volumes/*                configurable sandbox contract 授权挂载

Docker preflight 会检查：

  • Docker CLI 是否存在。
  • Docker daemon 是否可用。
  • runtime image 是否存在。
  • mounts / volumes / secrets / network 是否能按 sandbox contract 转成容器参数。

基础能力

工具系统

统一链路：

ToolProvider
  -> ToolSpec
  -> ToolRegistry
  -> ToolCompiler
  -> ToolExecutionGateway
  -> LangGraph ToolNode
  -> ToolMessage / Observation

内置基础工具分组：

filesystem:
  read
  write
  edit
  multi_edit
  glob
  grep
  ls

process:
  bash
  bash_status
  bash_stop

system:
  scheduler
  knowledge
  skill
  tool_output

network:
  web_fetch
  web_search

工具规则：

  • 工具 manifest 使用统一 ToolSpec。
  • 工具入口统一为 run(arguments: dict, resources: dict) -> dict。
  • 风险评估入口统一为 evaluate_risk(arguments: dict, context: dict) -> dict。
  • 参数先过 JSON Schema，再过风险策略，再执行 entrypoint。
  • 工具分低、中、高风险；中高风险可触发审批。
  • 长输出由 Gateway 归档完整结果，并把压缩预览写回模型。
  • 模型可用 tool_output 按引用读取完整工具输出。

Skill 与 MCP

  • Skill 通过系统内置 skill 工具递进式披露。
  • MCP 通过 provider 编译成统一 ToolSpec。
  • 生成 Agent 不把用户本机 MCP/Skill 写死进 package。
  • 用户后配置入口统一为 /runtime/extensions。

记忆系统

会话内记忆：

LangGraph messages channel
  + checkpointer
  + thread_id

跨会话记忆：

LangGraph BaseStore compatible store
  + namespace
  + background write jobs
  + retrieval / ranking / injection

Factory 与子 Agent 的 session、checkpoint、store 目录隔离。跨会话记忆写入不阻塞主对话。

知识系统

知识库通过系统工具 knowledge 管理和检索，不默认每轮自动召回。

支持的 source 类型：

filesystem
codebase
web_snapshot
database
mcp
skill
artifact_report
manual_note

支持两种模式：

  • index_only：catalog + SQLite FTS。
  • rag：chunk + embedding + LangGraph BaseStore semantic search。

子 Agent 知识根目录映射到：

/runtime/knowledge

上下文系统

ContextSystem 负责三件事：

  • 同步阻断式压缩当前会话 messages。
  • 从 ContextSource 检索候选上下文。
  • 在 cognitive 节点调用模型前组装临时上下文。

上下文注入不写入 checkpoint messages；压缩后的摘要会进入 messages，并保持 tool call / ToolMessage 配对完整。

定时任务系统

SchedulerSystem 使用：

  • SQLite job store 作为事实源。
  • APScheduler 作为时间触发引擎。
  • ToolExecutionGateway 执行 script/tool。
  • RuntimeKernel 执行 graph_run。

任务类型：

graph_run
script_run
tool_call

触发类型：

cron
interval
date

Trace 系统

TraceSystem 使用 JSONL Trace Fact Store。

每次运行写入：

/runtime/trace/runs/<trace_id>/manifest.json
/runtime/trace/runs/<trace_id>/trace.jsonl
/runtime/trace/runs/<trace_id>/refs.jsonl

RuntimeKernel 会记录：

  • run started / completed / failed
  • node span started / finished
  • model call span started / finished
  • tool/context/memory/render/subgraph 相关事件

Trace 是持久事实源；CLI 实时渲染仍消费 runtime events。

运行产物目录

.agentfactory/
  sessions/
  checkpoints/
  memory/
  scheduler/
  resources/
  assemblies/
  packages/
  harness/
  agent_runtime/

.agentfactory/ 是本地运行产物目录，不进入 Git。

验证

本项目不要求自行跑特化业务示例。常规改动优先使用语法、静态和非业务测试。

Python 语法检查：

python3 -m compileall -q agent_factory tests

TypeScript：

pnpm --dir cli typecheck
pnpm --dir cli lint
pnpm --dir cli test

静态检查：

git diff --check

未完成边界

  • /rerun <stage_id> 需要基于持久 bookmark/checkpoint 完整恢复。
  • graph_run 当前只向主链路 Graph 投递消息；动态 GraphPattern 选择仍需补齐。
  • Web UI 还未实现；当前以 CLI-first 为准。
  • Web UI 的 Trace 详情页还未实现；当前已提供 TraceReader、projection 与 diagnostics 底座。

参考文档

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

10 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages