X-Agents/core/agents/agent/context.py

"""Context builder for assembling agent prompts."""

import platform
from pathlib import Path
from typing import Any


class ContextBuilder:
    """Builds the context (system prompt + messages) for the agent."""

    def __init__(self, workspace: Path):
        """Initialize the context builder.

        Args:
            workspace: Workspace directory
        """
        self.workspace = workspace

    def build_system_prompt(self) -> str:
        """Build the system prompt with identity and runtime info."""
        workspace_path = str(self.workspace.expanduser().resolve())
        system = platform.system()
        runtime = f"{system} {platform.machine()}"

        return f"""# X-Agents Assistant

You are an AI assistant built on the X-Agents platform.

## Runtime
{runtime}

## Workspace
Your workspace is at: {workspace_path}

## Guidelines
- Be helpful and concise
- Think step by step when needed
- Ask for clarification when the request is ambiguous

## Tool Usage Guidelines
**IMPORTANT**: Only use tools when explicitly requested by the user:

**Use tools for**:
- Searching the web for current information
- Executing code or commands
- Reading or writing files
- Performing calculations

**DO NOT use tools for**:
- Simple questions and greetings (e.g., "介绍一下武汉", "你好", "什么是AI")
- General knowledge that you already know
- Conversational responses

For simple informational questions, respond directly from your knowledge without calling any tools.
"""

    def build_messages(
        self,
        history: list[dict[str, Any]],
        current_message: str,
    ) -> list[dict[str, Any]]:
        """Build the complete message list for an LLM call.

        Args:
            history: Conversation history
            current_message: Current user message

        Returns:
            List of messages for LLM
        """
        return [
            {"role": "system", "content": self.build_system_prompt()},
            *history,
            {"role": "user", "content": current_message},
        ]

    def add_assistant_message(
        self,
        messages: list[dict[str, Any]],
        content: str | None,
        tool_calls: list[dict[str, Any]] | None = None,
        reasoning_content: str | None = None,
    ) -> list[dict[str, Any]]:
        """Add an assistant message to the message list.

        Args:
            messages: Current message list
            content: Assistant message content
            tool_calls: Optional tool calls
            reasoning_content: Optional reasoning from model

        Returns:
            Updated message list
        """
        msg = {"role": "assistant", "content": content or ""}
        if tool_calls:
            msg["tool_calls"] = tool_calls
        if reasoning_content:
            msg["reasoning_content"] = reasoning_content
        messages.append(msg)
        return messages

    def add_tool_result(
        self,
        messages: list[dict[str, Any]],
        tool_call_id: str,
        tool_name: str,
        result: str,
    ) -> list[dict[str, Any]]:
        """Add a tool result to the message list.

        Args:
            messages: Current message list
            tool_call_id: ID of the tool call
            tool_name: Name of the tool
            result: Tool execution result

        Returns:
            Updated message list
        """
        messages.append({
            "role": "tool",
            "tool_call_id": tool_call_id,
            "name": tool_name,
            "content": result,
        })
        return messages