v0.4.0: Entity-World-Schedule Architecture

Breaking Changes

The multi-agent layer is rebuilt from scratch. easyagent/chat/ and
easyagent/runtime/ are deleted and replaced by three orthogonal protocols:

• Entity — id + async act(Perception) -> Action | None
• World — observe() / apply() / seed()
• Schedule — next(LoopState) -> list[str] | None
• Runtime — the perceive-act-apply loop wiring Entity + World + Schedule

The single-agent layer (Agent, ReactAgent, SkillAgent, SandboxAgent) is
unchanged.

What's New

Core Protocols

• Entity, World, Schedule — runtime-checkable protocols
• Perception with typed slices (MessagesSlice, SpatialSlice, StateSlice)
• Action hierarchy: Speak, Move, SetState, Silent, Composite
• Runtime — perceive-act-apply loop with optional EventBus

Worlds

• ConversationWorld — flat chat history, broadcast visibility
• PipelineWorld — entity N sees only seed + entity N-1
• SpatialWorld + Grid2D — 2D grid with range-limited perception
• StatefulWorld — decorator adding blackboard state to any World

Entities

• LLMEntity — wraps any Agent; rebuilds memory from Perception each turn
• TeamEntity — wraps a Runtime as a single Entity (recursive nesting)
• HumanEntity — asyncio.Queue or callback input

Schedules

• TakeTurns, RoundRobin, AllParallel, RandomOrder, Reactive
• Decorators: MaxTicks, UntilIdle, UntilPredicate

Presets

• sequential(), fanout(), debate(), chatroom(), groupchat()

Removed

• easyagent/chat/ — Orchestrator, Talker, LLMTalker, HumanTalker, RuntimeTalker,
  strategies/*
• easyagent/runtime/ — BaseRuntime, TickBasedRuntime, policies

Docs

• README, README_CN, CHANGELOG, docs/architecture.md all rewritten for the new
  architecture
• Examples 07–14 rewritten to demonstrate Entity-World-Schedule patterns

v0.3.0 — Chat layer + three-layer SDK

---

Release notes (markdown):

EasyAgent v0.3.0 is the biggest release since the SDK started. The runtime is
rebuilt around three layers, and a brand-new chat layer is the recommended
entry point for multi-agent collaboration.

Highlights

• 🆕 easyagent.chat — write multi-agent flows as plain await calls. Wrap
  any BaseAgent with LLMTalker, drop into a preset (sequential / fanout /
  chatroom / groupchat / debate), or compose your own Orchestrator along
  four pluggable axes (routing / turn-taking / stop / summarize). Containers nest
  natively because Orchestrator itself implements Talker.
• 🧱 Three-layer SDK — a single-agent ladder (Agent → ReactAgent →
  SkillAgent / SandboxAgent), a tick-driven runtime layer for autonomous
  group simulation, and the new chat layer for everyday multi-agent work.
• 📚 Examples ladder rebuilt — 15 single-concept examples, 00 through 14:
  model call → memory/context → tools → skills → sandbox → custom tool → two-agent
  talk → sequential → chatroom → groupchat → debate → nested → shared state →
  advanced runtime.

What's new

Single-agent layer

• BaseAgent / Agent / ReactAgent / SkillAgent / SandboxAgent clean
  inheritance chain, with loop logic now in agent.step().
• AgentSession (renamed from AgentRuntime) with an on_events(events) hook
  for multi-agent participation.
• BaseAgent.observe(msg) — read-only memory absorption without triggering a
  reply.
• Message.name field and Message.to_api_dict(include_reasoning=...).

Tools

• EndTool — the canonical "I'm done" tool, on by default in ReactAgent.
• ThinkTool — side-effect-free scratch pad, on by default in ReactAgent.
• ToolManager / SkillManager are now plain registries instead of
  constructor-level singletons.

Events & runtime (easyagent.events, easyagent.runtime)

• MessageEvent (visibility via to="*" or to=frozenset(...)), WaitEvent,
  EventBus, telemetry events.
• BaseRuntime, TickBasedRuntime, presets (ParallelRuntime /
  SequentialRuntime / ShuffledRuntime), policies (StepPolicy /
  SchedulePolicy / StopPolicy with all built-ins).

Chat layer (easyagent.chat)

• ChatMessage / Identity primitives.
• Talker protocol with adapters: LLMTalker, HumanTalker, RuntimeTalker.
• Orchestrator + strategies along four axes — see the README and
  docs/architecture.md.
• MultiAgentFormatter — folds others' messages into a <history> block so an
  agent never mistakes them for its own; auto-installed by LLMTalker.
• SharedState — versioned KV blackboard with subscriptions and async
  wait_for.

Removed

• easyagent/loop/ (SingleTurnLoop / ReActLoop) — loop logic now lives in
  agent.step().
• easyagent/pipeline/ (Team / BaseNode / BasePipeline) — superseded by
  chat.sequential and Orchestrator.

Install

pip install -U easy-agent-sdk==0.3.0

Optional extras: [sandbox] (Docker sandbox), [web] (SerperSearch), [all].

Full changelog

See https://github.com/SNHuan/EasyAgent/blob/v0.3.0/CHANGELOG.md

---

v0.1.4

[0.1.4] - 2026-01-20

Added

• Message.reasoning_content 字段: Message 模型新增 reasoning_content 可选字段，用于存储 LLM 的推理/思考内容（如 Claude 的 <think> 块）。这使得 agent 的 memory 能够完整保留模型输出的所有信息。

• Message.from_response() 类方法: 新增从 LLMResponse 直接创建 Message 的便捷方法。自动将 response 中的 content、reasoning_content 和 tool_calls 映射到 Message 对应字段。

• Message.to_api_dict() 方法: 新增将 Message 渲染为 LLM API 所需 dict 格式的方法。在发送给 LLM 时，自动将 reasoning_content 以 <think>...</think> 格式合并到 content 中，确保对话上下文的完整性。

Changed

• BaseAgent._build_messages(): 改用 Message.to_api_dict() 构建 API 请求消息，确保 reasoning_content 被正确渲染到对话历史中。

• LiteLLMModel cost 计算: 移除 cost 计算失败时的静默降级（设为 0），现在会直接抛出异常。确保模型配置正确，避免隐藏潜在问题。

Why This Matters

现代 LLM（如 Claude、DeepSeek）支持 "思考" 模式，会在 reasoning_content 字段返回推理过程。之前的实现只存储 content，导致：

1. 对话历史丢失了模型的推理上下文
2. 多轮对话时模型无法"回忆"之前的思考过程
3. 日志和 trajectory 无法完整记录模型行为

此次更新确保：

• ✅ Memory 完整存储 content + reasoning_content
• ✅ 发送给 LLM 时正确合并为完整上下文
• ✅ 支持 trajectory 导出完整的 thinking 记录

Migration Guide

无破坏性变更。现有代码无需修改即可继续工作。

如需利用新功能：

# 之前的写法（仍然有效）
msg = Message.assistant(content="Hello")

# 新写法：从 LLMResponse 直接创建（推荐）
response = await model.call_with_history(msgs)
msg = Message.from_response(response)

# 或者手动指定 reasoning_content
msg = Message.assistant(
    content="The answer is 42",
    reasoning_content="Let me think step by step..."
)

v0.1.3

🚀 New Features

Sandbox Module

• BaseSandbox Protocol - Abstract interface for isolated code execution
• DockerSandbox - Run code in Docker containers with resource limits (CPU, memory, network)
• LocalSandbox - Local shell execution for development/testing
• Automatic lifecycle management - Sandbox starts/stops with agent execution

SandboxAgent

• New SandboxAgent class extending ReactAgent with integrated sandbox
• Fine-grained configuration: cpu_limit, memory_limit, image, network, etc.
• Default tools: bash, write_file, read_file

Code Execution Tools

• bash - Execute shell commands in sandbox
• write_file - Safely write complex content (handles special characters, multi-line code)
• read_file - Read files from sandbox

Async Tool Execution

• Tools now support async execute() methods
• ToolAgent._execute_tool() auto-detects sync/async tools

📦 Dependencies

New optional dependency groups:

pip install easy-agent-sdk[sandbox]  # Docker SDK
pip install easy-agent-sdk[web]      # httpx for SerperSearch
pip install easy-agent-sdk[all]      # All optional deps

🔧 Improvements

• Export ModelConfig, AppConfig from easyagent.config
• Auto-discover tools with @register_tool decorator

📖 Usage

from easyagent import SandboxAgent
from easyagent.config import ModelConfig
from easyagent.model.litellm_model import LiteLLMModel

config = ModelConfig.load()
model = LiteLLMModel(**config.get_model("gpt-4o"))

agent = SandboxAgent(
    model=model,
    sandbox_type="docker",
    image="python:3.12-slim",
    cpu_limit=2.0,
    memory_limit="1g",
)

result = await agent.run("Write a fibonacci program and run it")

v0.1.2

What's New

• Add SerperSearch tool for Google search via Serper API

Usage

from easyagent.tool import SerperSearch  # auto-registered

agent = ReactAgent(model=model, tools=["serper_search"])

v0.1.1

What's New

Features

• Model kwargs support - Configure LiteLLM parameters (temperature, top_p, reasoning_effort, etc.) directly in config
• StepWindowMemory - New memory strategy for step-based history trimming with image support

Config Example

models:
  o3-mini:
    api_type: openai
    api_key: sk-xxx
    kwargs:
      reasoning_effort: high
      max_completion_tokens: 8192

Usage

from easyagent.memory import StepWindowMemory

# Keep last 10 text steps, last 3 image steps
memory = StepWindowMemory(text_steps=10, image_steps=3)

v0.1.0

🎉 Initial Release

A lightweight AI Agent framework built on LiteLLM.

Features

• Multi-model support via LiteLLM (OpenAI, Claude, Gemini, etc.)
• Tool calling with @register_tool decorator
• Memory strategies: Sliding Window & Auto-Summary
• ReAct reasoning loop
• DAG Pipeline for workflow orchestration
• Debug logging with token/cost tracking

Installation

pip install easy-agent-sdk