eino-employee-loop

Eino Employee Loop

中文

An event + scene driven decision loop for digital employees, built on CloudWeGo Eino. It answers one question per wake — given what just happened in this scene, which tools should the employee call, and is it done? — and leaves everything else to the Host that embeds it.

            Host (yours)                                   this module
 ┌──────────────────────────────────────────┐      ┌────────────────────────────┐
 │ channels ─► event.Event ─► catalog.Route ─┼─────►│ event: class · mode · lane │
 │ queues · windows · context assembly      │      │        session · cancels   │
 │ tools · permissions · receipts           │◄────►│ loop:  model ↔ tools,      │
 │ storage · replay · delivery              │      │        budgets, terminals  │
 └──────────────────────────────────────────┘      └────────────────────────────┘

Packages

The boundary

A Host calls the loop the same way it would call any other decision engine:

out, err := loop.New(loop.Config{
	Tools:               tools,          // the Host's capabilities
	Budget:              loop.DefaultBudget(),
	RequireTerminalTool: true,           // plain text is private; finish with a tool
}, model, host).Run(ctx, loop.Wake{Identity: id, Messages: messages})

• In: Config (tools, budget, protocol switches and hooks), an Eino model, a Host (Execute(ctx, Identity, ToolCall) (ToolResult, error)), and the wake's frozen messages.
• Out: Outcome — the decision (reply, quiet, dispatched, waiting), receipts, every tool outcome in call order, budget usage, token usage and the accepted transcript.

The types mirror a typical employee kernel (Tool, ToolCall, ToolResult, Decision, Receipt, ToolOutcome, Outcome, Budget), so an existing Host swaps engines by mapping fields, not concepts. Hooks keep Host policy outside the module: ValidateBatch, ValidateText, TurnTools (which tools each model call offers), RepairText, Permanent, and observers for model calls, tool calls, rejected batches and failures.

Rules the loop enforces:

• a batch is validated as a whole before any call runs (unknown or not-offered tools, exclusive tools, conflicting static terminal dispositions, argument schemas, Host rules) — a rejected batch is repaired, never half-executed;
• an effect without a Host receipt is never done;
• a Host refusal (ErrToolRefused) goes back to the model as a tool result;
• invalid output never enters the transcript;
• the budget bounds valid responses, consecutive errors and provider attempts.

Events and scenes

Every input is an event.Event. Its type fixes what happened (class) and why the employee received it (mode):

Routing gives each scene one foreground interactive session (triggered business events from people, serialized, human input first) and queued background sessions — observation (listening, preemptible), follow_up (one per task), routine (one per routine), lifecycle — plus a host lane for facts applied without waking a model. Addressed human input preempts observation windows; policy and subscription changes revoke them. See docs/events.md.

Run it locally

export LLM_BASE_URL=... LLM_API_KEY=... LLM_MODEL=...      # any OpenAI-compatible endpoint
export LANGFUSE_BASE_URL=... LANGFUSE_PUBLIC_KEY=... LANGFUSE_SECRET_KEY=...   # optional
go run ./cmd/eel -channel dws -profile <corpId:userId> -locale zh-CN       # a DingTalk account
go run ./cmd/eel -channel robot -robot-client-id <id> -robot-client-secret <secret>   # a Stream robot

See docs/local.md for both modes, Langfuse traces and running an eval suite against the local employee.

Documentation

• docs/events.md — classification, routing invariants, sessions, preemption, extension types.
• docs/host.md — what a Host implements: tools, receipts, refusals, wake assembly, storage, replay, delivery.
• docs/local.md — local verification.

Texts are multilingual: the loop's repair instructions (loop/locales), the local employee's prompt (local/locales) and event summaries (event/events.json) ship in en and zh-CN, with tests that keep the key sets equal. Add a locale by adding files.

License

MIT