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 such as eigent need to observe the agent execution lifecycle, including:

• agent step started / completed / failed
• tool call started / completed / failed

Currently, ChatAgent does not expose these as explicit callbacks or events. As a result, applications must rely on subclassing and overriding internal methods:

• step / astep
• _execute_tool / _aexecute_tool
• sometimes clone()

This creates tight coupling to internal implementation details and makes integrations harder to maintain.

There is also a runtime gap:

• when sync tools are executed from async paths, execution-local context may be lost (e.g., in executor-based execution)
• in stateful toolkit scenarios, applications still need custom clone() patches to propagate runtime / session / resource context

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