API 参考¶
公开 hiveflow Python API 参考。教程请参阅 快速入门。
HiveFlow¶
顶层编排引擎。
from hiveflow import HiveFlow, HiveFlowConfig
hf = HiveFlow(HiveFlowConfig())
await hf.start()
方法¶
| 方法 | 说明 |
|---|---|
start() |
启动事件总线与调度器 |
shutdown() |
停止 Worker、调度器、总线与黑板 |
create_agent(agent_id, skills, read_keys, write_keys, task_handler, max_queue_size=None) |
注册并启动 Worker |
register_agent_handler(agent_id, handler) |
注册状态恢复用的处理器 |
save_state() |
将 Agent 能力持久化到黑板 |
restore_state() |
从已保存状态恢复 Agent |
set_strategy(strategy) |
替换调度器选择策略(async) |
属性¶
| 属性 | 说明 |
|---|---|
config |
HiveFlowConfig 实例 |
blackboard |
SecureBlackboard(带审计的包装器) |
bus |
InProcessEventBus 或 RedisEventBus |
scheduler |
InProcessScheduler |
cell |
Cell 监督树 |
dag_orchestrator |
静态 DAG 编排器 |
dynamic_orchestrator |
运行时扩展编排器 |
HiveFlowConfig¶
@dataclass
class HiveFlowConfig:
scheduler: SchedulerConfig
blackboard_type: str = "memory"
encryption_key_provider: Optional[KeyProvider] = None
redis_url: Optional[str] = None
redis_db: int = 0
worker_max_queue_size: int = 100
log_level: str = "INFO"
# ...
| 字段 | 取值 / 说明 |
|---|---|
blackboard_type |
memory、ttl_memory、redis、encrypted |
redis_url |
使用 Redis 黑板/总线时必填 |
encryption_key_provider |
blackboard_type="encrypted" 时必填 |
类方法: HiveFlowConfig.from_env(prefix="HIVEFLOW") — 从环境变量加载。
ECM¶
Event-Condition-Messaging 单元 — 传递给 Agent 的任务消息。
ECM(
trace_id="trace-1",
intent="Process order",
intent_id="intent-1",
emitter="user",
required_skills=["process"],
payload={"order_id": "123"},
priority="normal",
)
Cell 与 Worker¶
Cell 管理 Worker 生命周期。应用代码中优先使用 HiveFlow.create_agent()。
任务处理器接收 (ecm, view),其中 view 为作用域黑板视图:
async def handler(ecm, view):
data = await view.get("input_key")
await view.put("output_key", {"result": data})
return {"ok": True}
Blackboard(黑板)¶
| 类 | 使用场景 |
|---|---|
MemoryBlackboard |
本地开发、测试 |
TTLMemoryBlackboard |
带 TTL 的内存黑板 |
RedisBlackboard |
分布式部署 |
EncryptedBlackboard |
静态 AES 加密 |
SecureBlackboard |
审计日志包装器(HiveFlow 默认使用) |
系统级键(编排器):await blackboard.sys_get(key) / sys_put(key, value)。
Scheduler(调度器)¶
SchedulerConfig(
selection_strategy="least_loaded", # least_loaded | auction | global_load
default_intent_timeout=60.0,
auction_timeout=5.0,
)
内置策略:LeastLoadedStrategy、AuctionStrategy、GlobalLoadAwareStrategy。
自定义策略继承 SelectionStrategy 并实现:
async def select(self, ecm, capabilities, worker_queues) -> List[str]:
...
HITL(Human-in-the-Loop)¶
| 类 | 角色 |
|---|---|
HITLManager |
创建门控、等待响应、处理超时 |
HITLGate |
门控状态 dataclass |
HITLAction |
APPROVAL、REVIEW、INPUT、CONFIRMATION |
HITLStatus |
PENDING、APPROVED、REJECTED、… |
mgr = HITLManager()
gate = await mgr.create_gate(workflow_id="wf", node_id="n1", action=HITLAction.APPROVAL, prompt="Approve?")
await mgr.respond(gate.gate_id, approved=True)
resolved = await mgr.wait_for_response(gate.gate_id)
CheckpointManager¶
mgr = CheckpointManager(MemoryCheckpointBackend())
cp_id = await mgr.save_checkpoint("wf-1", state={"step": 1})
cp = await mgr.restore_checkpoint(cp_id)
timeline = await mgr.get_checkpoint_timeline("wf-1")
fork_id = await mgr.fork(cp_id, branch_name="experiment")
Streaming(流式)¶
| 类 | 说明 |
|---|---|
StreamBuffer |
异步生产者/消费者事件缓冲 |
StreamEvent |
单个事件,含 type、data、node_id |
StreamEventType |
TOKEN、THOUGHT、TOOL_CALL、NODE_START、DONE、… |
collect_stream(buffer) |
将缓冲排空为列表 |
StreamEvent.to_sse() 格式化 Server-Sent Events 载荷。
Guards(守卫)¶
guard = InputGuard(max_length=10000)
result = guard.check(user_text) # InputGuardResult
validator = OutputValidator(max_length=50000)
result = validator.validate(agent_output) # OutputValidationResult
RAG¶
processor = DocumentProcessor()
doc = processor.parse_text("...", source="manual")
chunker = TextChunker(chunk_size=500, chunk_overlap=50)
pipeline = RAGPipeline(
vector_store=MemoryVectorStore(),
embedding_model=DummyEmbeddingModel(),
llm_client=client, # optional
)
await pipeline.add_document(doc, chunker)
result = await pipeline.query("What is AI?")
MCP¶
client = MCPClient(transport="mock")
client.register_tool("echo", lambda args: {"content": args.get("text", "")})
await client.initialize()
tools = await client.list_tools()
result = await client.call_tool("echo", {"text": "hello"})
MCPPluginManager 管理多个 MCP 服务器插件。PluginMarketplace 提供内置插件规格。
Cognitive Orchestrator(认知编排器)¶
from hiveflow import CognitiveOrchestrator, MockLLMClient
orchestrator = CognitiveOrchestrator(llm_client=MockLLMClient(response='{"plan":[...]}'))
result = await orchestrator.execute(goal="Research and summarize", task_fn=my_task_fn)
Evaluation(评估)¶
evaluator = Evaluator()
evaluator.add_criteria("accuracy", "Is the output correct?")
evaluator.add_custom_evaluator("accuracy", my_scorer_fn)
report = await evaluator.evaluate(
workflow_id="wf-1",
test_name="demo",
input_text="...",
output_text="...",
expected_output="...",
)
tester = ABTester(evaluator)
comparison = await tester.compare("input", agent_a_fn, agent_b_fn, "test_name")
Multimodal(多模态)¶
pipeline = MultiModalPipeline() # defaults to mock processors
image = MediaContent(media_type=MediaType.IMAGE, data=b"...")
analysis = await pipeline.analyze_image(image)
transcript = await pipeline.transcribe_audio(audio)
summary = await pipeline.summarize_video(video)