einoagent

package module
v0.3.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 4, 2026 License: MIT Imports: 0 Imported by: 0

README

eino-agent

Reusable Go runtime for Eino-based agents with AG-UI streaming and Datadog AI/LLM observability.

This repository provides embeddable Go packages for durable Eino agent orchestration. A consuming server supplies auth, routes, provider credentials, tool definitions, config loading, and deployment policy; eino-agent supplies runtime admission, durable session contracts, AG-UI replay/live-tail adapters, tool settlement, and observability/redaction policy.

State-aware provider adapters can also retain bounded opaque assistant continuation state across tool loops and process restarts. The runtime stores that state atomically with the owning assistant turn and restores it only at the matching adapter boundary; ordinary history, AG-UI, ledgers, extensions, and observability remain provider-neutral.

Module Baseline

  • Module: github.com/mattsp1290/eino-agent
  • Go: 1.26.3
  • Supported root release: v0.3.0 at commit 62b243dc99ff7b0d698507b428b474c1861e8712, verified on 2026-09-02 with make check and a fresh published consumer using no replace, workspace, vendor tree, or checkout access
  • Generated bindings: github.com/mattsp1290/eino-agent/wasmext/gen v0.1.0 via submodule tag wasmext/gen/v0.1.0
  • CloudWeGo Eino: github.com/cloudwego/eino v0.8.13
  • AG-UI bridge: github.com/mattsp1290/eino-agui v0.1.1
  • Observability: github.com/mattsp1290/eino-obs v0.0.0-20260627060807-a9a6f8bb478b
  • Coding tools: github.com/mattsp1290/eino-tools v0.1.1-0.20260825160656-63a3c99272c2

See docs/dependency-status.md for prerequisite evidence, docs/consumer-guide.md for the public embedding contract, docs/examples/minimal-server.md for a runnable server example, and docs/architecture/runtime.md for the package architecture.

Standard coding tools mount atomically through tools/einotools.MountStandard into composition.Registry; the runtime uses that registry as its runtime.RunPlanProvider.

Quick Embed

The smallest complete embedding is in examples/minimal-server:

go run ./examples/minimal-server -addr :8080

It wires:

  • store/sqlite as the durable transactional session.Store;
  • runtime.StreamingOrchestrator for run admission and interruption;
  • stream.Tail for live AG-UI deltas;
  • transport.SSEHandler for replay plus live tail;
  • a scripted Eino model resolver so the example runs without provider secrets.

Core route shape:

GET  /sessions/minimal/events
POST /sessions/minimal/runs
POST /runs/{run_id}/interrupt

Use it as a reference for composition, not as an auth or tenancy policy.

Local Gates

Run the full skeleton gate:

make check

Individual targets:

make fmt-check
make vet
make test
make race
make mod-tidy-check
make lint

make lint uses pinned golangci-lint v2.12.2 through go run. make fmt applies gofmt and pinned goimports.

Current Layout

  • doc.go: root package documentation.
  • session: durable session, run, message, part, tool-call, context-epoch, and replay contracts.
  • runtime: orchestration contracts for run admission, turn snapshots, interruption, tools, hooks, and internal events.
  • transport: embeddable HTTP adapters for AG-UI SSE replay/live-tail, interrupt, resume, and message decoding.
  • stream: bounded live-tail implementation for active runtime events.
  • model: provider/model catalog and Eino model resolution contracts.
  • config: immutable runtime config snapshot and validation contracts.
  • tools: typed tool definitions and per-run materialization helpers.
  • permissions: tool permission policy primitives.
  • agui: AG-UI durability and replay policy definitions; protocol mechanics stay in eino-agui.
  • obs: Datadog/eino-obs observability redaction and correlation policy definitions.
  • store/sqlite: embedded SQLite store implementation.
  • store/storetest: reusable durable store contract tests for backend implementations.
  • examples/: buildable embedding and integration sketches.
  • docs/: durable planning and architecture context.
  • .github/workflows/ci.yml: CI gate matching the local Makefile targets.

Durability Model

Replayable conversation state is stored as sessions, runs, messages, ordered parts, tool calls, context epochs, and selected event records. Live AG-UI SSE frames and model deltas are transport output, not the replay source of truth. Reconnects reconstruct snapshots from durable messages/parts and then attach to the active live tail.

See docs/architecture/agui-events.md and docs/architecture/storage.md for the detailed rules.

Integration Guides

  • docs/architecture/web-search-extension-ownership.md: delegated ownership and public runtime seams for the eino-agent-extensions web-search adapter.
  • docs/consumer-guide.md: public API, storage, tool lifecycle, observability, configuration, and migration guidance.
  • docs/integrations/datadog.md: Datadog/eino-obs exporter wiring and safe default redaction.
  • docs/integrations/ag-ui-go-server-example.md: AG-UI server migration sketch.
  • docs/integrations/ensemble.md: future ensemble adapter options and non-parity caveat.

Documentation

Overview

Package einoagent provides a reusable Go runtime for Eino-based agents.

Public runtime contracts live in subpackages such as session, runtime, model, and config. The root package is reserved for top-level assembly helpers.

Source Files

View all Source files

Directories

Path Synopsis
Package agui defines AG-UI durability and replay policy for eino-agent.
 Package agui defines AG-UI durability and replay policy for eino-agent.
Package catalog contains model catalog implementations that list provider metadata without creating provider transports.
 Package catalog contains model catalog implementations that list provider metadata without creating provider transports.
Package composition coordinates typed extension callbacks and scoped tool definitions under one atomic mount and one per-run quiescence lease.
 Package composition coordinates typed extension callbacks and scoped tool definitions under one atomic mount and one per-run quiescence lease.
Package config defines runtime configuration snapshots and hook boundaries.
 Package config defines runtime configuration snapshots and hook boundaries.
plugins
Package agentcontext defines bounded context-source assembly and propagation metadata shared by runtime, tools, model adapters, and host integrations.
 Package agentcontext defines bounded context-source assembly and propagation metadata shared by runtime, tools, model adapters, and host integrations.
examples
ag-ui-go-server-example
Package agui_go_server_example sketches how the Fiber-based ag-ui-go-server-example can embed eino-agent without copying runtime internals.
 Package agui_go_server_example sketches how the Fiber-based ag-ui-go-server-example can embed eino-agent without copying runtime internals.
datadog
Package datadogexample shows environment-driven eino-obs wiring for eino-agent runtimes.
 Package datadogexample shows environment-driven eino-obs wiring for eino-agent runtimes.
ensemble-adapter
Package ensembleadapter sketches a future adapter from ensemble dispatcher events to eino-agent runtime events.
 Package ensembleadapter sketches a future adapter from ensemble dispatcher events to eino-agent runtime events.
minimal-server command
native-extension
Package nativeextension demonstrates one reversible, session-scoped plugin mounted through the same typed runtime points used by curated Wasm adapters.
 Package nativeextension demonstrates one reversible, session-scoped plugin mounted through the same typed runtime points used by curated Wasm adapters.
Package extension provides typed, deterministic runtime extension points, atomic mount ownership, immutable scoped plans, and quiescent teardown.
 Package extension provides typed, deterministic runtime extension points, atomic mount ownership, immutable scoped plans, and quiescent teardown.
internal
deps
Package deps anchors the initial dependency baseline for the module skeleton.
 Package deps anchors the initial dependency baseline for the module skeleton.
jsonequal
Package jsonequal compares JSON values without losing numeric precision.
 Package jsonequal compares JSON values without losing numeric precision.
jsonobject
Package jsonobject validates and decodes JSON objects without accepting duplicate top-level keys.
 Package jsonobject validates and decodes JSON objects without accepting duplicate top-level keys.
providerstatewire
Package providerstatewire defines the dependency-neutral wire invariants shared by the public model boundary and durable session encoding.
 Package providerstatewire defines the dependency-neutral wire invariants shared by the public model boundary and durable session encoding.
workspace
Package model defines provider and model catalog contracts for resolving Eino chat models without coupling runtime orchestration to one vendor SDK.
 Package model defines provider and model catalog contracts for resolving Eino chat models without coupling runtime orchestration to one vendor SDK.
Package obs defines eino-agent observability and redaction policy.
 Package obs defines eino-agent observability and redaction policy.
Package permissions defines runtime tool permission policy decisions and simple rule-based policy hooks.
 Package permissions defines runtime tool permission policy decisions and simple rule-based policy hooks.
providers
fake
Package fake provides an in-memory provider adapter for tests and host development.
 Package fake provides an in-memory provider adapter for tests and host development.
Package runtime defines orchestration contracts for admitting and executing Eino agent runs over durable sessions.
 Package runtime defines orchestration contracts for admitting and executing Eino agent runs over durable sessions.
Package session defines durable session, run, message, part, tool-call, and context-epoch contracts for eino-agent runtimes.
 Package session defines durable session, run, message, part, tool-call, and context-epoch contracts for eino-agent runtimes.
compaction
history
Package store documents durable store implementation expectations.
 Package store documents durable store implementation expectations.
sqlite
Package sqlite provides a local durable session store backed by SQLite.
 Package sqlite provides a local durable session store backed by SQLite.
storetest
Package storetest provides reusable contract tests for session.Store implementations.
 Package storetest provides reusable contract tests for session.Store implementations.
Package tools provides typed tool definitions and per-run materialization for definitions selected and sealed by composition.
 Package tools provides typed tool definitions and per-run materialization for definitions selected and sealed by composition.
agui
einotools
session
Package wasmext adapts explicitly configured WebAssembly components to eino-agent's native Go extension seams.
 Package wasmext adapts explicitly configured WebAssembly components to eino-agent's native Go extension seams.
gen module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.