Hooking Functions

Hooking functions are extension points that let you customize agent behavior at specific execution points without modifying the agent’s core code.

Logging and Monitoring

Log the agent’s internal state, reasoning process, and actions for debugging and analysis.

Customizing Behavior

Modify or intercept the input/output of core functions to extend or override agent behavior.

In AgentScope, hooking functions attach to the following core agent functions:

Core function	Hook points	Description
`reply`	`pre_reply`, `post_reply`	Before/after the agent replies to a message
`observe`	`pre_observe`, `post_observe`	Before/after the agent observes external information
`print`	`pre_print`, `post_print`	Before/after printing a message to the output (terminal, web interface, etc.)
`_reasoning`	`pre_reasoning`, `post_reasoning`	Before/after the agent performs reasoning (thinking, tool use)
`_acting`	`pre_acting`, `post_acting`	Before/after the agent takes actions (calling tools)

Hooking Signature

To simplify the usage, AgentScope provides unified signatures for all hooks.

Pre-hooks

All the pre-hooks have the same signature:

	Name	Description
Arguments	`self`	The agent instance, which can be used to access the agent’s internal state and methods.
	`kwargs`	The input keyword arguments.
Returns	`dict[str, Any] \| None`	The modified keyword arguments to be passed to the core function or the next hook.

A pre-hook template looks like this:

def pre_hook_template(
    self: AgentBase | ReActAgentBase,
    kwargs: dict[str, Any],
) -> dict[str, Any] | None:  # The modified displayed message
    """Pre hook template."""
    pass

Post-hooks

All post-hooks have an additional output argument, which is the output of the core function or the previous hook. If the core function has no output, the output will be None.

	Name	Description
Arguments	`self`	The agent instance, which can be used to access the agent’s internal state and methods.
	`kwargs`	The input keyword arguments.
	`output`	The output of the target function or the most recent non-None return value from previous hooks
Returns	`Any`	The modified output to be returned to the next hook or the caller. If `None`, the original output will be used.

The post-hook template looks like this:

def post_hook_template(
    self: AgentBase | ReActAgentBase,
    kwargs: dict[str, Any],
    output: Any,  # The output of the target function
) -> Any:  # The modified output
    """Post hook template."""
    pass

Hook Management

Registration and Execution

AgentScope provides the following APIs to manage the hooking functions:

API	Description
`register_instance_hook`	Register a hook function to a specific agent instance.
`remove_instance_hook`	Remove a hook function from a specific agent instance.
`clear_instance_hooks`	Clear all hook functions from a specific agent instance.

Once registered, the hooks will be executed automatically at the corresponding execution points of the core functions. Execution order:

Hooks are executed in registration order.
Multiple hooks can be chained together.

Return value handling:

For pre-hooks, non-None return values are passed to the next hook or core function, that is
- When a hook returns None, the next hook will use the most recent non-None return value from previous hooks
- If all previous hooks return None, the next hook receives a copy of the original arguments
- The final non-None return value (or original arguments if all hooks return None) is passed to the core function
The post-hooks works similarly as the pre-hooks.

Never call a core function (reply, observe, _reasoning, _acting) from within a hook — doing so creates an infinite loop.

Example

Tasking the pre-reply hook as an example, we first create a hook function that modifies the input messages before replying:

def instance_pre_reply_hook(
    self: AgentBase,
    kwargs: dict[str, Any],
) -> dict[str, Any]:
    """A pre-reply hook that modifies the message content."""
    msg = kwargs["msg"]
    msg.content += "[instance-pre-reply]"
    # return modified kwargs
    return {
        **kwargs,
        "msg": msg,
    }

Then we can register the hook function to a specific agent instance:

from agentscope.agent import ReActAgent

agent = ReActAgent(...)
agent.register_instance_hook(
    hook_type="pre_reply",
    hook_name="test_pre_reply",
    hook=instance_pre_reply_hook
)

Now, when the agent is called to reply a message, the instance_pre_reply_hook will be executed before the reply, and the message content will be modified accordingly.

Get Started

Tutorial

Out-of-box Agents

Basic Concepts

Building Blocks

Observe & Evaluate

Tune Agent

Deploy & Serve

Others

Logging and Monitoring

Customizing Behavior

Hooking Signature

Pre-hooks

Post-hooks

Hook Management

Registration and Execution

Example

Logging and Monitoring

Customizing Behavior

​Hooking Signature

​Pre-hooks

​Post-hooks

​Hook Management

​Registration and Execution

​Example

Hooking Signature

Pre-hooks

Post-hooks

Hook Management

Registration and Execution

Example