[Feature Request] Pre-Invocation Prompt Hook

[coolbeevip]

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

In the current model invocation pipeline, prompts (system/user/tool messages) go straight to the model backend with no interception point.
Yet real-world enterprise and agent-framework scenarios often require dynamically adjusting prompts before invocation — such as injecting user identity or applying platform-wide governance rules.
Without a unified pre-invocation hook, these requirements cannot be implemented consistently or sustainably.

A unified pre-invocation hook not only enables these capabilities but also cleanly supports common cross-business features currently implemented in scattered, model-coupled code paths, such as:

• Removing <think> tags https://github.com/camel-ai/camel/blob/master/camel/models/base_model.py#L140
• Executing guard/validation logic https://github.com/camel-ai/camel/blob/master/camel/runtimes/llm_guard_runtime.py#L64

Centralizing these behaviors in a hook reduces business coupling, improves maintainability, and provides a consistent, extensible governance layer across all models.

Solution

No response

Alternatives

No response

Additional context

No response

[Wendong-Fan]

Hi @coolbeevip , thank you for this well-structured feature request, this proposal is reasonable and valuable, added it to current develop sprint

[coolbeevip]

Here are my initial thoughts:

• ChatAgent should accept a hook handler chain during construction, used to intercept/modify request/response around model calls.
• The hook chain follows the chain-of-responsibility pattern: each node’s returns a boolean to continue or break.
• Each node must implement a common interface with two abstract methods: one for pre-processing (before the model call) and one for post-processing (after the model call)

A Scenario

When a user asks a question such as "Show the health report of the devices I'm responsible for," the system should automatically perform the following actions:

Before calling LLM:

Inject the user's profile into the message array (e.g., a list of devices the user maintains). This allows the model to provide accurate, personalized answers based on the user's responsibilities.

After receiving the model's response:

Automatically remove all messages containing the user's profile from the message list, ensuring that no sensitive information is stored in the conversation history or logs, and that no sensitive information is displayed to the user.

This achieves personalization while avoiding the leakage of private data and avoiding the need to write such logic in various agents.

Actual messages sent to the LLM

[
  {
    "role": "system",
    "content": "You are an intelligent support assistant for operations engineers. You must answer queries strictly based on the user's authorized device scope."
  },
  {
    "role": "system",
    "content": "【User Profile (visible only for this invocation)】\n- User ID: u_12345\n- User Name: John Doe\n- Devices under responsibility: [DEV-001, DEV-002, DEV-005]\n- Region: Beijing Core Data Center\nUse this profile when interpreting queries related to 'my devices'. Do not reference devices outside this scope.",
  },
  {
    "role": "user",
    "content": "Show the health report of the devices I'm responsible for."
  }
]

Messages visible to the end user

[
  {
    "role": "user",
    "content": "Show the health report of the devices I'm responsible for."
  },
  {
    "role": "assistant",
    "content": "Sure. Here is the recent 7-day health summary for your responsible devices:\n\n- DEV-001: CPU usage stable around 35%, no major alerts.\n- DEV-002: Two short packet-loss alerts in the last 24 hours, automatically recovered.\n- DEV-005: Disk usage at 82%; consider planning for expansion this week.\n\nLet me know if you want detailed trends for any specific device."
  }
]

[zshanhui]

Are we looking for something to this?

class ModelProcessHook(ABC):
    @abstractmethod
    def pre_process(self, messages: List[OpenAIMessage]) -> List[OpenAIMessage] # or Tuple[bool, List[OpenAIMessage]] if supporting "short circuit" if returns False
        pass

    @abstractmethod
    def post_process(self, messages: List[OpenAIMessage]) -> ChatCompletion # or Tuple[bool, ChatCompletion]
        pass


class MedicalRecordHook(ModelProcessHook):
    def pre_process(self, messages: List[OpenAIMessage]) -> List[OpenAIMessage]
        print("insert medical id context...")
        return message

    def post_process(self, messages: List[OpenAIMessage]) -> ChatCompletion
        print('remove or redact medical id records...')
        return message


class DefaultModelProcessHook(ModelProcessHook):
    def pre_process(self, messages: List[OpenAIMessage]) -> List[OpenAIMessage]
         # move original contents of BaseModelBackend.preprocess_messages()
        # removes thinking content and formats for parallel tool calls

    def post_process(self, ...) -> ...
        # noop
        return messages


class ChatAgent(BaseAgent):
    __init__(..., hooks: Optional[List[ModelProcessHook]]):
        self._model_hooks: List[ModelProcessHook] = list(hooks or [])

    # chain-of-responsibility helpers
    def _apply_pre_hooks(
        self, messages: List[OpenAIMessage]
    ) -> List[OpenAIMessage]:
        processed = messages
        for hook in self._model_hooks:
            processed = hook.pre_process(processed)
            # if False, we can return to stop further processing
        return processed

    def _apply_post_hooks():
         ... // similar loop with _apply_pre_hooks

    def _get_model_response(...):
        ...
        processed_messages = self.apply_pre_hooks(openai_messsages)
        for attempt in range(self, retry_attempts):
            try:
                resp = self.model_backend.run(...)
                if resp:
                    break
             ...
         resp = self._apply_hooks_post_hooks(resp)
         sanitized = self._sanitize_messages_for_logging(...)
         ... # rest of code

    # insert hooks into other methods that get model responses

i should have some time this weekend to implement a PR if this is close to the general idea of what we want. i can add an example as well to demonstrate the usage.