ReMe/doc/quick_start.md

# Quick Start

Here is a simple user guide.

### Step0: Configuration
- start es
- set env APIKEY / host
- python -m model_service -port 8000 -config simple/path

### Step1: Own an agent

Assume you have a runnable [agent code](./mxc_agent.py).
Here, we use a basic LLM combined with a simple react framework including three tools(code, web_search, terminate) as an example.

```python
class MxcAgent(BaseModel):
    llm: BaseLLM | None = Field(default=None)
    max_steps: int = Field(default=10)
    tools: List[BaseTool] = Field(default_factory=list)

    def think(self, query: str, **kwargs) -> bool:
        ...

    def act(self, **kwargs):
        ...

    def run(self, query: str, **kwargs) -> List[Message]:
        messages: List[Message] = []

        for i in range(self.max_steps):
            should_act: bool = self.think(query, messages=messages, **kwargs)
            if should_act:
                self.act(messages=messages, **kwargs)
            else:
                break
        return messages

    
query = "Analyze Xiaomi Corporation
agent = MxcAgent(llm=OpenAICompatibleBaseLLM(model_name="qwen3-32b", temperature=0.0001),
                 max_steps=10,
                 tools=[CodeTool(), DashscopeSearchTool(), TerminateTool()])
messages = agent.run(query=query)
answer = messages[-1].content
print(answer)
```

### Step2: Implement AgentWrapper

In order to utilize the **context generator** and **summarizer** capabilities of beyondagent, please inherit from **MxcAgent** and **BaseAgentWrapperMixin** to implement the AgentWrapper.

Here, you need to customize two parts:
- how to integrate the content message(insight) generated by the `self.context_generator` into the context.
- implement the execute function to output the trajectory.

Below is a simple example of integrating **trajectory-level insight** into the context.

```python
from beyondagent.core.module.agent_wrapper.base_agent_wrapper import BaseAgentWrapperMixin

class MxcAgentWrapper(MxcAgent, BaseAgentWrapperMixin):
    def execute(self, query: str, **kwargs) -> Trajectory:
        trajectory = Trajectory(steps=messages, query=query)
        context_msg = self.context_generator.execute(trajectory=trajectory)
        new_query = f"""
previous insight:
{context_msg.content}
Please consider the helpful parts from these in answering the question, to make the response more comprehensive and substantial.

user query:
{query}
        """.strip()
        
        messages = self.run(new_query, **kwargs)
        return Trajectory(query=query, steps=messages, answer=messages[-1].content, done=True)

```

### Step3: Run AgentRunner with insight

Once you have completed the implementation of the AgentWrapper class, you will be able to utilize the capabilities of
beyondagent. 

Here is an example using **SimpleAgentRunner**. 
We first executed two historical tasks, then summarized the experience and made it persistent. 
Finally, we utilized the historical experience in a new task.

[insights demo](./insight.json)


```python
from beyondagent.core.module.runner.simple_agent_runner import SimpleAgentRunner



mxc_agent_wrapper = MxcAgentWrapper(llm=OpenAICompatibleBaseLLM(model_name="qwen3-32b", temperature=0.0001),
                                    max_steps=10,
                                    tools=[CodeTool(), DashscopeSearchTool(), TerminateTool()])
agent_runner = SimpleAgentRunner(agent_wrapper=mxc_agent_wrapper, summarizer="default", context_generator="default")

# historical tasks
agent_runner.rollout_trajectory(query="Analyze the company Tesla.")
agent_runner.rollout_trajectory(query="Analyze the company Apple.")

# summary insights and store them
agent_runner.summary_and_store()

# run agent with historical insights
trajectory = agent_runner.rollout_trajectory(query="Analyze the company Xiaomi Corporation.")
```


### Step4: Evaluation(Optional)

If we have a reward function that allows us to compare the performance before and after adding context, we can try this
part.

Use `run_agent` to obtain the answer from the original agent (answer1), and use `run_agent_wrapper` to get the answer
with added insights and experience (answer2).

Here, the reward function is used to compare and score the two answers. The `reward.reward_value` indicates the win rate
of answer2.

```python
# task
query = "Analyze Xiaomi Corporation."

# run agent
agent = MxcAgent(llm=OpenAICompatibleBaseLLM(model_name="qwen3-32b", temperature=0.0001),
                 max_steps=10,
                 tools=[CodeTool(), DashscopeSearchTool(), TerminateTool()])
messages = agent.run(query=query)
answer1 = messages[-1].content

# agent runner: Assume we already have some historical experience.
mxc_agent_wrapper = MxcAgentWrapper(llm=OpenAICompatibleBaseLLM(model_name="qwen3-32b", temperature=0.0001),
                                    max_steps=10,
                                    tools=[CodeTool(), DashscopeSearchTool(), TerminateTool()])
agent_runner = SimpleAgentRunner(agent_wrapper=mxc_agent_wrapper, summarizer="default", context_generator="default")
trajectory = agent_runner.rollout_trajectory(query=query)
answer2 = trajectory.answer

# pair-wise LLM evaluation
from beyondagent.core.module.reward_fn.simple_reward_fn import SimpleRewardFn
reward_fn = SimpleRewardFn(llm=OpenAICompatibleBaseLLM(model_name="qwen3-32b", temperature=0.0001))
reward = reward_fn.execute(query=query, answer1=answer1, answer2=answer2, eval_times=5)
print(f"final reward={reward.reward_value}")
```