AgentKit

中文文档

AgentKit is a lightweight, event-stream-driven Go library for building reliable agents on top of CloudWeGo Eino ADK. It keeps the first agent small, while providing sessions, durable goals, context compaction, skills, MCP, and tool governance when an application grows.

Inspired by pi-agent-core, AgentKit focuses on a simpler public API and production-safe defaults.

Why AgentKit

• Easy to start — create an Agent and call Ask; no graph or middleware wiring is required.
• Easy to observe — use request-scoped streams or global events for text, reasoning, tools, compaction, goals, interrupts, and errors.
• Easy to keep running — persist sessions, checkpoints, goals, and large tool results; reconnect by stable IDs after a client or process restart.
• Safe by default — concurrent-run protection, panic isolation, bounded cleanup, tool-call repair, result limits, and optimistic concurrency are built in.
• Composable when needed — add declarative subagents, skills, MCP servers, tool search, reduction, retry/failover, HITL, and multimodal input independently.

Installation

AgentKit requires Go 1.25.14 or later.

go get github.com/wsshow/agentkit@latest

Five-Minute Start

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/cloudwego/eino-ext/components/model/openai"
	"github.com/wsshow/agentkit"
)

func main() {
	ctx := context.Background()

	chatModel, err := openai.NewChatModel(ctx, &openai.ChatModelConfig{
		APIKey: "your-api-key",
		Model:  "gpt-4o",
	})
	if err != nil {
		log.Fatal(err)
	}

	agent, err := agentkit.New(ctx, &agentkit.Config{
		Name:         "assistant",
		SystemPrompt: "You are a helpful assistant.",
		Model:        chatModel,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer agent.Close()

	result, err := agent.Ask(ctx, "Hello!")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(result.Text)
}

Ask is the simplest blocking API. For real-time text and tool progress, use Stream:

stream, err := agent.Stream(ctx, "Explain MCP")
if err != nil {
	log.Fatal(err)
}
defer stream.Close()

for event := range stream.Events() {
	if event.Type == agentkit.EventMessageDelta {
		fmt.Print(event.Delta)
	}
}
result, err := stream.Wait()

See Runtime and events for the complete run API, lifecycle rules, HITL, queues, and multimodal input.

Choose the Capabilities You Need

Need	Start here
Run methods, events, cancellation, HITL, queues, multimodal input	Runtime and events
Manage many isolated conversations for users or tenants	Multi-session management
Restore conversations and checkpoints after restart	Sessions and persistence
Run a multi-step objective for hours or days and reconnect safely	Durable goals
Wake goals from cron, queues, or cloud schedulers	Scheduling and wakeups
Delegate focused work to isolated specialist agents	Subagents
Keep long conversations inside the model context window	Context management
Load reusable SKILL.md instructions on demand	Skills
Connect stdio, SSE, or Streamable HTTP MCP servers	MCP
Govern tools, repair calls, reduce large results, or search a catalog	Tool management
Test without a live model or external tools	Testing

The documentation index includes recommended reading paths and links between related topics.

A Practical Production Baseline

Most stateful agents should begin with a durable session and automatic compaction. Enable result reduction when tools may return large payloads:

store, err := agentkit.NewFileSessionStore("./data/agent")
if err != nil {
	log.Fatal(err)
}

agent, err := agentkit.New(ctx, &agentkit.Config{
	Name:  "assistant",
	Model: chatModel,
	Session: &agentkit.SessionConfig{
		ID:    "user-123",
		Store: store,
	},
	Compaction: &agentkit.CompactionConfig{
		MaxTokens:       80_000,
		KeepRecentTurns: 2,
	},
	ToolReduction: &agentkit.ToolReductionConfig{},
})

The file store is designed for a local single-process worker. Multi-replica services should implement the persistence interfaces with transactional database semantics; see Sessions and persistence and Durable goals.

Built-In Tool Middleware Decisions

AgentKit includes the three capabilities that remove recurring application work without exposing Eino middleware plumbing:

• Dangling tool-call repair is always on because valid history is a correctness requirement.
• Large-result reduction is one opt-in zero-value configuration because it changes storage and model-visible content.
• On-demand tool search is opt-in because it is useful for large catalogs but adds an extra model decision for small ones.

See Tool management for defaults, ordering, and extension points.

Examples

Example	What it demonstrates
simple	Minimal multi-turn conversation
tools	Tool calls and progress events
history	Manual history export and restore
session	Multi-session management and cross-process restore
goal	Durable objective execution and reconnect
subagents	Declarative specialist delegation and correlated events
compaction	Automatic context compaction
skills	Local SKILL.md discovery and loading
mcp	Streamable HTTP MCP integration
queues	Steering and follow-up queues
hitl	Human interrupt and resume
multimodal	Text and image input

Project

• Contributing
• Security policy
• License