[Feature Request] Add lifecycle callbacks, execution context propagation, and improved clone semantics to ChatAgent

[fengju0213]

Required prerequisites

• I have searched the Issue Tracker and Discussions that this hasn't already been reported. (+1 or comment there if it has.)
• Consider asking first in a Discussion.

Motivation

Background

Applications (e.g., eigent) that need to observe the agent execution lifecycle currently have no framework-level way to do so. The required observations include:

• Agent step started / completed / failed
• Tool call started / completed / failed
• Runtime metadata (request ID, task ID, etc.) attached to each event

No callback/event API exists. Applications must subclass ChatAgent and override internal methods (step, astep, _execute_tool, _aexecute_tool, clone) to inject lifecycle hooks. This couples downstream code to internal implementation details.

contextvars context is lost in async-to-sync tool execution. When ChatAgent dispatches sync tools to a thread pool from an async path (astep → _aexecute_tool → run_in_executor), contextvars.ContextVar values set by the caller are silently dropped. The same applies to FunctionTool.async_call and the step() timeout executor path. This breaks any middleware or instrumentation that relies on ContextVar propagation.

clone() loses runtime configuration. Several fields set at construction time are not carried over to the cloned agent, including mask_tool_output, retry_attempts, retry_delay, step_timeout, enable_snapshot_clean, stream_accumulate, and summary_window_ratio. Applications must patch these manually after cloning. Additionally:

• There is no way to pass a session ID or execution context to the clone.
• response_terminators are shared by reference — mutating one agent's terminator state affects the other.
• Stateful toolkits that expose clone_for_new_session(session_id) have no way to receive a caller-specified session ID.

Solution

Extend ChatAgent with the following capabilities:

1. Lifecycle callbacks

Introduce a standard callback/event interface (e.g., AgentCallback / AgentEvent) with:

• step_started
• step_completed
• step_failed
• tool_started
• tool_completed
• tool_failed

These should be triggered by the framework without requiring subclassing.

---

2. Execution context propagation

Ensure execution-local context is preserved during tool execution, especially:

• when sync tools are invoked from async paths
• when execution is delegated to thread pools / executors

---

3. Improved clone semantics

Enhance clone() to:

• preserve full runtime configuration
• support optional propagation of execution / session context
• better support stateful toolkits without requiring local patches

Alternatives

No response

Additional context

No response