v0.6.6

EasyAgent 0.6.6 tightens multi-agent runtime semantics and improves MCP tool
result normalization. Runtime ticks now use a clearer observe/act/apply split,
and MCP integrations preserve structured provider results more reliably.

Changed

• Runtime tick execution now snapshots all active entity perceptions before
  running entity actions, then applies actions in deterministic active-entity
  order.
• Multi-entity ticks now run the act() phase concurrently with
  asyncio.gather() while keeping the action log deterministic.
• Runtime tick is now synchronized into worlds that expose set_tick(), making
  Perception.tick follow the runtime tick source of truth.
• Worlds may now expose advance(tick) for optional per-tick world dynamics;
  StatefulWorld forwards both set_tick() and advance() to its inner
  world.
• MCP result normalization now prefers structuredContent /
  structured_content over less precise data payloads.
• MCP structured values are converted through a JSON-safe normalizer before
  serialization, including pydantic-style model_dump(), legacy dict(),
  root, bytes, mappings, and iterables.

Fixed

• Avoided MCP result output falling back to opaque root-like object strings
  when a structured content payload is available.
• Preserved plain content output ahead of fallback data when MCP providers
  return both.

v0.6.5

[0.6.5] - 2026-06-10

EasyAgent 0.6.5 adds first-class wrappers for externally managed coding
agents. Claude Code SDK and Codex SDK can now be registered as runtime
entities, traced through the existing event system, and inspected in the local
dashboard.

Added

• easyagent.external with ExternalAgentEntity, ExternalResult,
  ExternalRunner, ClaudeCodeRunner, CodexRunner, claude_code_entity,
  and codex_entity.
• Optional dependency groups: external, claude, and codex for installing
  Claude Code SDK and Codex SDK integrations only when needed.
• Real external agent examples:
  • examples/16_external_claude_code.py
  • examples/17_external_codex.py
• .env.example as the single local environment example for EasyAgent core,
  Serper, Claude Code SDK, and Codex/OpenAI SDK configuration.
• register_token_usage_adapter() for provider-specific token usage
  normalization.

Changed

• Runtime tracing now supports external agent provider events, including
  messages, streaming deltas, tool calls, tool results, final results, failures,
  and provider session ids.
• The dashboard Messages view now renders external agent transcripts with
  user prompts on the right and agent process/final messages on the left.
• Claude Code and Codex tool results are summarized by default; long result
  payloads stay collapsed until expanded in the dashboard.
• Token usage normalization now understands OpenAI/Codex-style
  input_tokens / output_tokens payloads and Claude cache token details.
• README and README_CN now reference the unified .env.example and include the
  updated dashboard screenshot.

Removed

• Removed the older .example_env file to avoid ambiguity with
  .env.example.

Install

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

v0.6.4

EasyAgent v0.6.4

EasyAgent 0.6.4 adds a lightweight display protocol for custom trace events. SDK users can now persist user-defined events and tell the dashboard how to render them, without changing the trace store schema or modifying frontend code.

Highlights

• Added CustomTraceEvent for user-defined trace events with explicit persisted event types.
• Added DisplayHint for attaching dashboard rendering metadata to custom events.
• Dashboard now supports rendering custom events in the Messages tab via payload.display.surface == "messages".
• Custom event display.title and display.content now improve Timeline summaries.
• Custom events can be hidden from Timeline with display.surface == "hidden" while still being persisted and inspectable through payloads.
• README and README_CN now include examples for publishing custom dashboard-visible events.

Example

await bus.publish(
    CustomTraceEvent(
        event_type="PlannerStepEvent",
        session_id="sess_planner",
        agent_id="planner",
        summary="Planner selected search_docs",
        payload={"step": "search_docs"},
        display=DisplayHint.messages(
            "Need to inspect README and pyproject first.",
            role="assistant",
            title="Planner step",
            source="planner",
        ),
    )
)

v0.6.3

EasyAgent v0.6.3

EasyAgent 0.6.3 is a dashboard polish release for the runtime observability work introduced in 0.6.2. It improves runtime/session timeline rendering, preserves runtime navigation state, and fixes token usage tooltip positioning.

Highlights

• Added a runtime timeline view that mixes runtime events and child sessions in timestamp order.
• Runtime event selection now updates the Event Payload inspector directly.
• Runtime and session timeline connector lines are now rendered at the container level, fixing broken or misaligned lines caused by zoom level or variable row heights.
• Returning from a session opened from the runtime timeline now restores the runtime timeline tab instead of resetting to Overview.
• Token Usage bar chart tooltips now align correctly at chart edges, so first/last bar tooltips are not clipped.
• README dashboard guidance no longer references removed example scripts.

Verification

• npm run lint
• npm run build
• python -m pytest

All Python tests passed: 78 passed.

Install

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

v0.6.1

EasyAgent v0.6.1

EasyAgent 0.6.1 polishes the local dashboard experience for real streaming agent runs. The dashboard now updates while an LLM response is still being generated, keeps stream-heavy timelines readable, and presents token usage with clear current-session versus all-session scopes.

Highlights

• Added LLMStreamChunkEvent trace events during Agent.stream() and ReactAgent.stream().
• Dashboard messages now render partial assistant output before the final LLMRespondedEvent.
• SSE trace updates now detect SQLite table changes instead of relying on DB file mtimes.
• Timeline collapses consecutive stream chunk events into one grouped row.
• Token Usage now has Current and All modes.
• Current shows the selected session input/output mix as a donut chart.
• All shows all sessions as an hourly stacked bar chart.
• Token totals now follow the selected Token Usage scope.
• Filter and Trace DB popovers now close on outside click or Escape.
• Event mix and token usage charts now include subtle reveal animations.
• Trace DB source is configured at startup with easyagent dashboard --db path/to/traces.db.
• Removed dashboard-only helper scripts from apps/dashboard/scripts.

Install

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

v0.6.0

EasyAgent 0.6.0

EasyAgent 0.6.0 adds the observability loop for real agent development: session tracing, persistent stores, streaming responses, Agent Skills-compatible loading, and a bundled local dashboard launched from the CLI.

Highlights

• Added easyagent dashboard to inspect local agent traces.
• Added SQLite / JSONL / memory trace stores.
• Added structured tracing for agent lifecycle, LLM calls, tool calls, tool results, failures, and final messages.
• Added streaming model response support through LLMStreamChunk.
• Added Agent Skills-compatible SKILL.md loading with .easyagent/skills and EA_SKILLS_DIR.
• Removed default end / think tools; ReAct now finishes naturally when the model returns a plain assistant response.
• Moved tests out of the package into top-level tests/.
• Added dashboard UI for sessions, timelines, messages, token usage, payloads, event mix charts, and resizable panes.

Install

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

v0.5.1: MCP Tool Integration

EasyAgent now supports MCP as an external tool source. Users can point the SDK
at a FastMCP/MCP config, discover remote tools, register them into a
ToolManager, and decide per AgentSession which tools are visible to the
model.

Added

MCP integration (easyagent/mcp/)

• MCPToolset — discovers tools from a FastMCP-compatible source and exposes
  them as EasyAgent tools.
• load_mcp_tools(source, *, servers=None, tags=None) — returns MCP-backed
  tool adapters without mutating a registry.
• register_mcp_tools(tool_manager, source, *, servers=None, tags=None) —
  incrementally registers discovered MCP tools into an existing ToolManager
  and returns the registered tool names.
• MCPToolAdapter — bridges MCP tool calls into EasyAgent's Tool protocol.
• FastMCPClientAdapter — wraps fastmcp.Client while keeping FastMCP as an
  implementation detail of the MCP module.
• MCPToolInfo / MCPToolResult plus result normalization helpers for MCP
  text, structured content, resource blocks, and errors.

Tool selection

• MCP config server names can be used as natural categories via
  servers=["literature"].
• FastMCP tool tags are preserved from meta["_fastmcp"]["tags"] and can be
  filtered with tags=[...].
• MCP tool registration is additive: registering one MCP server does not clear
  existing local or remote tools.

Examples

• examples/mcp/fastmcp_in_memory.py — in-memory FastMCP server consumed by
  EasyAgent.
• examples/mcp/config_load.py — loads mcp_config.example.json, registers a
  selected MCP server's tools, and enables them on a session.
• examples/mcp/mcp_config.example.json — standard mcpServers config.
• examples/mcp/servers/literature_server.py — small local FastMCP server for
  examples.

Tests

• easyagent/test/test_mcp.py covers MCP tool discovery, ToolManager
  registration, tag filtering, server filtering, and result normalization.

Changed

• easyagent top-level exports now include MCPToolset, load_mcp_tools,
  and register_mcp_tools.
• Default installation now includes sandbox, web, and MCP dependencies:
  docker, httpx, and fastmcp.
• requirements.txt now mirrors the default runtime dependency set.
• README.md and README_CN.md document MCP config loading and session-level
  tool enablement.
• MCP examples live under examples/mcp/ instead of the numbered learning
  path, because MCP is an external integration rather than a core ladder step.

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..."
)