### Quick Setup Script for Yunjue Agent

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/README.md

This bash script automates the cloning, installation, and initial setup of the Yunjue Agent. It clones the repository, makes the install script executable, runs the installation, copies example configuration files, and activates the virtual environment before starting the evolution process.

```bash
# 1. Clone and setup
git clone https://github.com/YunjueTech/Yunjue-Agent.git && cd Yunjue-Agent

chmod +x install.sh

./install.sh

# NOTE: `install.sh` installs the `codex` CLI, but you still need to configure Codex yourself
# (e.g., set `OPENAI_API_KEY` and optionally `CODEX_PROFILE` in your environment).
cp .env.example .env

cp conf.yaml.example conf.yaml

source .venv/bin/activate

./scripts/evolve.sh --dataset DEEPSEARCHQA --run_name test --batch_size 1 --start 0
```

--------------------------------

### Configure HTTP Client with Proxy in Python

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/src/prompts/templates/tool_enhancement.md

Demonstrates how to configure an httpx client to use a specified proxy URL for making HTTP requests. This is crucial for accessing external networks when a proxy is required. Ensure the proxy URL is correctly provided and timeouts are set appropriately.

```python
with httpx.Client(proxy="{{ proxy_url }}", timeout=timeout) as client:
    resp = client.request(method, url, headers=headers, json=json)
    resp.raise_for_status()
    return resp.json()
```

--------------------------------

### Fetch URL Content to Markdown using Crawl4ai in Python

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/src/prompts/templates/tool_enhancement.md

Shows the correct pattern for using Crawl4ai to fetch web page content and convert it to Markdown. It emphasizes mandatory configurations like `magic=True` and `BrowserConfig`, and the use of `contextlib.redirect_stdout` to manage output. This method is suitable for LLM consumption and should not be used for binary files.

```python
import asyncio
import io
import contextlib
from crawl4ai import AsyncWebCrawler, BrowserConfig
async def main():
    f = io.StringIO()
    with contextlib.redirect_stdout(f):
        async with AsyncWebCrawler(magic=True, config=BrowserConfig(user_agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/116.0.0.0 Safari/537.36")) as crawler:
            result = await crawler.arun(
                url="https://google.com",
            )
            content = result.markdown
```

--------------------------------

### Input and Output Model Definition

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/src/prompts/templates/toolsmiths_agent.md

This Python snippet illustrates how to define InputModel and OutputModel classes based on a tool request's input and output schemas. It shows type inference from example values and the use of Pydantic's Field for descriptions and defaults.

```python
from pydantic import BaseModel, Field
from typing import Optional

# Example schema inferred from TOOL_REQUEST
# input_schema = {
#     "query": {"type": "string", "description": "The search query"},
#     "limit": {"type": "integer", "description": "Maximum number of results", "default": 10}
# }
# output_schema = {
#     "results": {"type": "array", "items": {"type": "string"}},
#     "total": {"type": "integer"}
# }

class InputModel(BaseModel):
    query: str = Field(..., description="The search query")
    limit: Optional[int] = Field(10, description="Maximum number of results")

class OutputModel(BaseModel):
    results: list[str] = Field(..., description="List of search results")
    total: int = Field(..., description="Total number of results found")

def run(input: InputModel) -> OutputModel:
    # Tool logic here
    # Example placeholder:
    print(f"Running with query: {input.query}, limit: {input.limit}")
    return OutputModel(results=["result1", "result2"], total=2)
```

--------------------------------

### Python Tool Enhancement: Original Code Structure

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/src/prompts/templates/tool_enhancement.md

This snippet represents the original Python tool code that requires enhancement. It serves as the baseline for modifications, including the '__TOOL_META__', 'InputModel', 'OutputModel', and 'run' function.

```python
{{ original_tool_code }}
```

--------------------------------

### Python Data Types for State Management

Source: https://context7.com/yunjuetech/yunjue-agent/llms.txt

This Python code defines core data types used for state management and structured outputs in the Yunjue Agent system. It includes base classes for `State`, `TaskExecutionContext`, `ToolRequest`, `ToolExecutionRecord`, `StepToolAnalysis`, `ResponseAnalysis`, and `LLMType`. An example `ExampleState` class and a `ToolRequest` object are provided.

```python
from src.schema.types import (
    State,
    TaskExecutionContext,
    ToolRequest,
    ToolExecutionRecord,
    StepToolAnalysis,
    ResponseAnalysis,
    LLMType
)
from pydantic import BaseModel

# State - The main workflow state passed between nodes
class ExampleState(State):
    user_query: str = "What is AI?"
    final_answer: str = ""
    task_execution_count: int = 0
    pending_step_response: str = ""
    recur_limit_exceeded: bool = False

# ToolRequest - Definition for a new tool to be created
tool_request = ToolRequest(
    name="stock_price_fetcher",
    description="Fetch current stock prices from financial APIs",
    input_schema={"symbol": {"type": "string", "description": "Stock ticker symbol"}},
    output_schema={"price": {"type": "number"}, "currency": {"type": "string"}}
)
```

--------------------------------

### Execute Graph Query with Initial State and Configuration

Source: https://context7.com/yunjuetech/yunjue-agent/llms.txt

This Python script demonstrates how to invoke a compiled graph with an initial state and configuration. It sets up a user query and configuration parameters like thread ID and tool directories, then prints the final answer from the graph's execution. It requires the 'asyncio' library and a pre-defined 'graph' object.

```python
import asyncio

async def run_graph():
    initial_state = {
        "user_query": "What is machine learning?",
        "messages": []
    }

    config = {
        "configurable": {
            "thread_id": "task_001",
            "dynamic_tools_dir": "output/tools/private",
            "dynamic_tools_public_dir": "output/tools/public"
        }
    }

    final_state = await graph.ainvoke(input=initial_state, config=config)
    print(f"Final answer: {final_state['final_answer']}")

asyncio.run(run_graph())
```

--------------------------------

### JSON Output Structure for Tool Usage

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/src/prompts/templates/step_tool_analyzer.md

This JSON structure outlines the required fields for describing tool usage. It includes a list of necessary tool names, guidance on their application, and detailed definitions for any new tools that need to be requested, including their input and output schemas.

```json
{
  "required_tool_names": ["tool_name_1", "tool_name_2"],
  "tool_usage_guidance": "tool_name_1: Sketch of how this tool supports the task within 20 words;\ntool_name_2: Another high-level usage hint",
  "tool_requests": [
    {
      "name": "tool_name",
      "description": "Tool description",
      "input_schema": {
        "type": "object",
        "properties": {
          "param1": {
            "type": "string",
            "description": "Parameter description"
          }
        },
        "required": ["param1"]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "result": {
            "type": "string"
          }
        },
        "required": ["result"]
      }
    }
  ]
}
```

--------------------------------

### Pydantic v2 Field Validation Example (Python)

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/src/prompts/templates/toolsmiths_agent.md

Illustrates the correct usage of Pydantic v2's `@field_validator` for validating individual fields within a Pydantic model. This replaces the deprecated `@validator` and `@root_validator`. Ensure all field validations adhere to this pattern.

```python
from pydantic import BaseModel, Field, field_validator

class MyModel(BaseModel):
    my_field: str

    @field_validator('my_field')
    @classmethod
    def validate_my_field(cls, v):
        if not v or len(v) < 5:
            raise ValueError('my_field must be at least 5 characters long')
        return v

# Example usage:
# try:
#     model = MyModel(my_field='short')
# except ValueError as e:
#     print(e)
```

--------------------------------

### Configure HTTP Client with Proxy and Timeout (Python)

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/src/prompts/templates/toolsmiths_agent.md

Demonstrates how to configure an httpx client to use a proxy URL and a specified timeout for network requests. This is essential for accessing external networks securely and efficiently. Ensure the proxy URL and timeout are correctly set.

```python
import httpx
timeout = 10 # Example timeout in seconds
proxy_url = "http://your-proxy-url.com"
method = "GET"
url = "http://example.com"
headers = {}
json_payload = {}

with httpx.Client(proxy=proxy_url, timeout=timeout) as client:
    resp = client.request(method, url, headers=headers, json=json_payload)
    resp.raise_for_status()
    print(resp.json())
```

--------------------------------

### Load and Execute Dynamic Tools

Source: https://context7.com/yunjuetech/yunjue-agent/llms.txt

Load and execute dynamically created tools from Python files. Tools are executed in an isolated Python environment for safety. This includes loading multiple tools from a directory or creating a single tool from a module file and invoking it.

```python
from src.tools.dynamic_tool_loader import (
    load_dynamic_tools,
    get_dynamic_tools,
    create_tool_from_module
)
from pathlib import Path

# Load all dynamic tools from a directory
tools = load_dynamic_tools(
    tools_directory="output/run/dynamic_tools_public",
    user_query="Find stock prices"
)

print(f"Loaded {len(tools)} dynamic tools")
for tool in tools:
    print(f"  - {tool.name}: {tool.description[:50]}...")

# Create a single tool from a module file
tool = create_tool_from_module(
    file_path=Path("output/run/dynamic_tools/web_search.py"),
    user_query="Search the web"
)

if tool:
    # Execute the tool with arguments
    result = tool.invoke({"query": "latest news"})
    print(f"Tool result: {result}")

# Dynamic tool file format (web_search.py):
"""
from pydantic import BaseModel, Field

__TOOL_META__ = {
    "name": "web_search",
    "description": "Search the web for information",
    "dependencies": ["requests", "beautifulsoup4"]
}

class InputModel(BaseModel):
    query: str = Field(..., description="Search query")

def run(input: InputModel) -> dict:
    # Tool implementation
    return {"results": [...]}
"""
```

--------------------------------

### Tool Entrypoint Function (Python)

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/src/prompts/templates/toolsmiths_agent.md

Presents the `run` function, the primary entrypoint for the Python tool. This function takes an `InputModel` instance, performs necessary validations (including API keys from environment variables), executes the core logic, and returns an `OutputModel` instance.

```python
def run(input: InputModel) -> OutputModel:
    # validate inputs → validate API keys from os.environ (per policy)
    # do work (local, file I/O, subprocess, and/or networking)
    # Follow the API Key & Service Policy: Prefer high-quality keyed APIs.
    # normalize → return OutputModel
```

--------------------------------

### Common Configuration for Yunjue Agent

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/docs/reproduce.md

Sets up environment variables and configuration files for running the Yunjue Agent. This includes defining task execution limits, worker recursion limits, tool enhancement intervals in `.env`, and specifying model configurations in `conf.yaml`.

```bash
# .env settings
MAX_TASK_EXECUTION_CNT=8
MAX_WORKER_RECURSION_LIMIT=10
WORKER_TOOL_ENHANCE_INTERVAL=5

# conf.yaml settings
BASIC_MODEL.model: gemini-3-pro
CLUSTER_MODEL.model: gemini-3-pro
VISION_MODEL.model: gemini-3-flash
SUMMARIZE_MODEL.model: gemini-3-flash
TOOL_ANALYZE_MODEL.model: gpt-5-mini
```

--------------------------------

### Analyze Tool Requirements with StepToolAnalysis

Source: https://context7.com/yunjuetech/yunjue-agent/llms.txt

The StepToolAnalysis class represents the output of an analysis step, detailing which tools are required for a task, guidance on their usage, and specific tool requests. This helps in planning and executing multi-step tasks.

```python
analysis = StepToolAnalysis(
    required_tool_names=["web_search", "calculator"],
    tool_usage_guidance="First search for data, then calculate the result",
    tool_requests=[tool_request]
)
```

--------------------------------

### Create Configured LLM Instances with create_llm

Source: https://context7.com/yunjuetech/yunjue-agent/llms.txt

Factory function to create configured LLM instances based on type. Reads configuration from conf.yaml and supports multiple model roles like basic, vision, summarize, and cluster. It utilizes LangChain's HumanMessage for interaction and retrieves token limits using get_max_tokens.

```python
from src.services.llms.llm import create_llm, get_max_tokens
from src.schema.types import LLMType
from langchain_core.messages import HumanMessage

# Create basic LLM for general agent tasks
basic_llm = create_llm(LLMType.BASIC)
response = basic_llm.invoke([HumanMessage(content="Hello, world!")])
print(response.content)

# Create vision-capable LLM for image analysis
vision_llm = create_llm(LLMType.VISION)

# Create summarization LLM for context compression
summarize_llm = create_llm(LLMType.SUMMARIZE)

# Get token limit for context management
max_tokens = get_max_tokens(LLMType.BASIC)  # Returns token_limit from conf.yaml
print(f"Max tokens: {max_tokens}")

# LLM types available:
# LLMType.BASIC        -> BASIC_MODEL config
# LLMType.VISION       -> VISION_MODEL config
# LLMType.SUMMARIZE    -> SUMMARIZE_MODEL config
# LLMType.CLUSTER      -> CLUSTER_MODEL config
# LLMType.TOOL_ANALYZE -> TOOL_ANALYZE_MODEL config
```

--------------------------------

### Run Evolution Loop for XBENCH-scienceqa

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/docs/reproduce.md

Executes the evolution loop for the XBENCH-scienceqa dataset. Uses the common configuration and the `evolve.sh` script with dataset and run name set to 'XBENCH-scienceqa'.

```bash
./scripts/evolve.sh --dataset XBENCH-scienceqa --run_name xbench-scienceqa --batch_size 16
```

--------------------------------

### Load Benchmark Datasets with Python

Source: https://context7.com/yunjuetech/yunjue-agent/llms.txt

The `load_dataset` function loads benchmark datasets in a batched iterator format. It automatically downloads and prepares datasets from HuggingFace if they are not found locally. This function is useful for iterating through training or evaluation data.

```python
from dataloader import load_dataset

# Load DeepSearchQA dataset with batch size of 16
data_iter = load_dataset("DEEPSEARCHQA", batch_size=16)

for batch in data_iter:
    data_items = batch["data_items"]
    for item in data_items:
        task_id = item["task_id"]  # Unique identifier for the task
        query = item["query"]       # The question/prompt text
        print(f"Task {task_id}: {query[:100]}...")

# Supported datasets:
# - "HLE"                  # Humanity's Last Exam benchmark
```

--------------------------------

### Run Evolution Loop with Bash Scripts

Source: https://context7.com/yunjuetech/yunjue-agent/llms.txt

Executes the agent's evolution loop for training and optimizing tools on benchmark datasets. Supports various configurations like resuming from checkpoints, custom timeouts, and different merging policies. The output includes predictions, logs, and evolved tools.

```bash
# Basic evolution run on DeepSearchQA dataset
./scripts/evolve.sh --dataset DEEPSEARCHQA --run_name my_experiment --batch_size 16

# Resume from a specific step with custom timeout
./scripts/evolve.sh --dataset HLE --run_name hle_run --batch_size 4 --start 10 --train_steps 20 --timeout 600

# Run with LLM-based tool merging policy
./scripts/evolve.sh --dataset FINSEARCHCOMP --run_name finsearch_run --batch_size 5 --merge_policy llm

# Output structure after running:
# output/my_experiment/
#   predictions.jsonl          # Model predictions in JSONL format
#   logs/                      # Per-task execution logs
#   dynamic_tools_public/      # Evolved public tools (.py files)
#   private_dynamic_tools/     # Per-task private tools
#   checkpoints/               # Tool checkpoints per batch step
```

--------------------------------

### YAML Model Configuration Reference

Source: https://context7.com/yunjuetech/yunjue-agent/llms.txt

This YAML file defines configurations for various models used within the system, including basic, vision, summarization, clustering, tool analysis, and evaluation models. Each model configuration specifies parameters such as base URL, model name, API key (referenced from environment variables), temperature, token limit, and maximum retries.

```yaml
# conf.yaml - Model configurations
BASIC_MODEL:
  base_url: https://api.openai.com/v1
  model: "gpt-4"
  api_key: ${OPENAI_API_KEY}
  temperature: 0.7
  token_limit: 200000
  max_retries: 3

VISION_MODEL:
  base_url: https://api.openai.com/v1
  model: "gpt-4-vision-preview"
  api_key: ${OPENAI_API_KEY}
  temperature: 0.7
  token_limit: 128000

SUMMARIZE_MODEL:
  base_url: https://api.openai.com/v1
  model: "gpt-4"
  api_key: ${OPENAI_API_KEY}
  temperature: 0.2
  token_limit: 200000

CLUSTER_MODEL:
  base_url: https://api.openai.com/v1
  model: "gpt-4"
  api_key: ${OPENAI_API_KEY}
  temperature: 0.2
  token_limit: 200000

TOOL_ANALYZE_MODEL:
  base_url: https://api.openai.com/v1
  model: "gpt-4"
  api_key: ${OPENAI_API_KEY}
  temperature: 0.2
  token_limit: 200000

EVAL_MODEL:
  base_url: https://api.openai.com/v1
  model: "gpt-4"
  api_key: ${OPENAI_API_KEY}
  temperature: 0
  token_limit: 200000
```

--------------------------------

### Run Evolution Loop for XBENCH-deepsearch

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/docs/reproduce.md

Executes the evolution loop for the XBENCH-deepsearch dataset. Uses the common configuration and the `evolve.sh` script with dataset and run name set to 'XBENCH-deepsearch'.

```bash
./scripts/evolve.sh --dataset XBENCH-deepsearch --run_name xbench-deepsearch --batch_size 16
```

--------------------------------

### Run Evolution Loop with Yunjue Agent

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/docs/reproduce.md

Executes the evolution loop for a specified dataset using the `evolve.sh` script. Requires dataset name, run name, and batch size as arguments.

```bash
./scripts/evolve.sh --dataset <DATASET> --run_name <RUN_NAME> --batch_size 16
```

--------------------------------

### Run Evolution Loop for FinSearchComp Dataset

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/docs/reproduce.md

Executes the evolution loop for the FinSearchComp dataset. Uses the common configuration and the `evolve.sh` script with dataset and run name set to 'FINSEARCHCOMP'.

```bash
./scripts/evolve.sh --dataset FINSEARCHCOMP --run_name finsearchcomp --batch_size 16
```

--------------------------------

### Build LangGraph State Machine with build_graph

Source: https://context7.com/yunjuetech/yunjue-agent/llms.txt

Builds the LangGraph state machine that orchestrates the agent workflow. Returns a StateGraph builder with all nodes (manager, tool_developer, executor, integrator) connected, defining the agent's execution flow.

```python
from src.core.builder import build_graph
from src.schema.types import State

# Build the graph
builder = build_graph()

# Compile for execution
graph = builder.compile()

# The graph implements this workflow:
# START -> manager -> tool_developer -> executor -> manager (loop)
#                                                -> integrator -> END

```

--------------------------------

### Environment Variables Configuration Reference

Source: https://context7.com/yunjuetech/yunjue-agent/llms.txt

This .env file specifies environment variables required for the Yunjue Agent. It includes API keys for TAVILY and OpenAI, Codex CLI profile settings, recursion and task execution limits, tool enhancement intervals, optional proxy URL, and LangSmith tracing configurations.

```bash
# .env - Environment variables
TAVILY_API_KEY=tvly-xxxxx              # For web search tools
OPENAI_API_KEY=sk-xxxxx                # For Codex CLI
CODEX_PROFILE=default                   # Optional Codex profile

MAX_WORKER_RECURSION_LIMIT=10           # Max tool steps per worker
MAX_TASK_EXECUTION_CNT=8                # Max manager retries per task
WORKER_TOOL_ENHANCE_INTERVAL=5          # Steps between tool enhancement

PROXY_URL=http://127.0.0.1:7897         # Optional proxy for tools

# LangSmith tracing (optional)
LANGSMITH_TRACING=false
LANGSMITH_API_KEY=lsv2_xxxxx
LANGSMITH_PROJECT=yunjue-agent
```

--------------------------------

### Optimize Tools After Batch Execution

Source: https://context7.com/yunjuetech/yunjue-agent/llms.txt

This Python function, `optimize_after_batch`, utilizes functions from the 'evolve' library to optimize tool libraries after a batch of tasks. It takes task IDs, a step number, and a run directory as input. The optimization process involves clustering similar tools and merging them based on a specified policy ('naive' or 'llm'). It returns a boolean indicating success or failure.

```python
from evolve import optimize_tools, cluster_tools, merge_tools, naive_merge_tools
import asyncio
from pathlib import Path

# After processing a batch, optimize the tool library
async def optimize_after_batch():
    task_ids = ["task_001", "task_002", "task_003"]
    step = 5
    run_dir = Path("output/my_run")

    # Optimize tools: cluster similar tools and merge them
    success = await optimize_tools(
        task_ids=task_ids,           # Tasks that completed this batch
        step=step,                   # Current batch step number
        run_dir=run_dir,             # Run directory
        merge_policy="naive"         # "naive" or "llm" for LLM-based merging
    )

    print(f"Tool optimization {'succeeded' if success else 'failed'}")

# Cluster tools by similarity (LLM-based or naive)
tool_meta_list = [
    {"name": "web_search_01", "description": "Search the web", "input_schema_code": "..."},
    {"name": "web_search_02", "description": "Web search tool", "input_schema_code": "..."},
    {"name": "calculator", "description": "Perform calculations", "input_schema_code": "..."}
]

clusters = cluster_tools(tool_meta_list)
# Returns: [
#   {"suggested_master_tool_name": "web_search", "tool_names": ["web_search_01", "web_search_02"]},
#   {"suggested_master_tool_name": "calculator", "tool_names": ["calculator"]}
# ]

asyncio.run(optimize_after_batch())
```

--------------------------------

### Manage Task Execution Context with TaskExecutionContext

Source: https://context7.com/yunjuetech/yunjue-agent/llms.txt

The TaskExecutionContext class manages the state during a task's execution. It holds a list of available tools, a history of tool executions, and an accumulated summary of the context. This allows the agent to maintain state and refer to past actions.

```python
context = TaskExecutionContext(
    bound_tools=[],                    # Tools available to the worker
    tool_executions=[execution_record], # History of tool executions
    context_summary=""
)
```

--------------------------------

### Implement ReAct Agent with LangGraph

Source: https://context7.com/yunjuetech/yunjue-agent/llms.txt

The ReAct-style agent implementation using LangGraph. It supports tool enhancement, context summarization, and automatic rollback on empty responses. The agent can be invoked synchronously or asynchronously with streaming.

```python
from src.agents.react import ReActAgent
from src.services.llms.llm import create_llm
from src.schema.types import LLMType
from langchain_core.messages import HumanMessage

# Create LLM and tools
llm = create_llm(LLMType.BASIC)
tools = []  # List of LangChain tools

# Initialize ReAct agent with configuration
agent = ReActAgent(
    llm=llm,
    tools=tools,
    max_steps=10,                              # Max tool execution iterations
    max_retries=3,                             # Max rollback attempts
    tool_enhance_interval=5,                   # Steps between tool enhancement
    dynamic_tools_dir="output/run/tools",      # Private tools directory
    dynamic_tools_public_dir="output/public",  # Shared tools directory
    user_query="Find the GDP of Japan",        # Original query for context
    failure_report=None,                       # Previous failure report (retry scenario)
    context_summary=None                       # Accumulated context summary
)

# Invoke the agent synchronously
result = agent.invoke({
    "messages": [HumanMessage(content="Find the current GDP of Japan")],
    "tool_steps": 0,
    "retry_count": 0
})

# Or use async streaming for real-time updates
import asyncio

async def run_agent():
    async for state in agent.astream(
        {"messages": [HumanMessage(content="What is 2+2?")]},
        stream_mode="values"
    ):
        if "messages" in state:
            print(f"Messages: {len(state['messages'])}")

asyncio.run(run_agent())
```

--------------------------------

### URL Fetching with Crawl4ai

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/src/prompts/templates/toolsmiths_agent.md

This Python code demonstrates the mandatory usage pattern for Crawl4ai to fetch web page content. It includes necessary imports, instantiation of AsyncWebCrawler with specific configurations, and capturing stdout to suppress logs.

```python
import asyncio
import io
import contextlib
from crawl4ai import AsyncWebCrawler, BrowserConfig

async def fetch_url_content(url: str):
    f = io.StringIO()
    with contextlib.redirect_stdout(f):
        async with AsyncWebCrawler(magic=True, config=BrowserConfig(user_agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/116.0.0.0 Safari/537.36")) as crawler:
            result = await crawler.arun(url=url)
            return result.markdown

# Example usage:
# async def main():
#     content = await fetch_url_content("https://example.com")
#     print(content)
#
# asyncio.run(main())
```

--------------------------------

### Record Tool Execution with ToolExecutionRecord

Source: https://context7.com/yunjuetech/yunjue-agent/llms.txt

The ToolExecutionRecord class is used to store details about a single execution of a tool. It captures information such as the tool's name, caller and tool message IDs, tool call ID, arguments passed to the tool, the result obtained, and any errors encountered.

```python
execution_record = ToolExecutionRecord(
    tool_name="web_search",
    caller_message_id="msg_001",
    tool_call_id="call_001",
    tool_message_id="msg_002",
    arguments={"query": "Python tutorials"},
    result={"results": [...]},
    error=None
)
```

--------------------------------

### Execute Single Query with Python

Source: https://context7.com/yunjuetech/yunjue-agent/llms.txt

The `run_task` function executes a single user query through the LangGraph agent pipeline. It handles task initialization, logging, and dynamic tool management. The function returns a JSON string containing the final answer and a reasoning summary.

```python
import asyncio
from pathlib import Path
from src.main import run_task

async def execute_single_query():
    # Execute a query through the agent pipeline
    result = await run_task(
        user_input="What is the capital of France and its population?",
        run_dir=Path("output/test_run"),
        debug=False,
        task_id="query_001"
    )

    # Result is a JSON string containing final_answer and reasoning_summary
    # {"final_answer": "Paris, population ~2.1 million", "reasoning_summary": "..."}
    print(f"Result: {result}")
    return result

# Run the async function
result = asyncio.run(execute_single_query())
```

--------------------------------

### Run Evolution Loop for DeepSearchQA Dataset

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/docs/reproduce.md

Executes the evolution loop for the DeepSearchQA dataset. Uses the common configuration and the `evolve.sh` script with dataset and run name set to 'DEEPSEARCHQA'.

```bash
./scripts/evolve.sh --dataset DEEPSEARCHQA --run_name deepsearchqa --batch_size 16
```

--------------------------------

### Evaluate Agent Predictions with Python Scripts

Source: https://context7.com/yunjuetech/yunjue-agent/llms.txt

Evaluates the agent's predictions against ground truth for various benchmarks using LLM-based judging. This script loads prediction files, compares them to specified datasets, and outputs detailed metrics. It supports multiple benchmarks and configurable worker counts.

```bash
# Evaluate DeepSearchQA predictions
uv run scripts/evaluate.py \
    --benchmark deepsearchqa \
    --predictions output/my_experiment/predictions.jsonl \
    --dataset dataset/DEEPSEARCHQA/DSQA-full.json \
    --max-workers 30

# Evaluate HLE benchmark
uv run scripts/evaluate.py \
    --benchmark hle \
    --predictions output/hle_run/predictions.jsonl \
    --dataset dataset/HLE/hle.json \
    --max-workers 30

# Evaluate XBench with custom output directory
uv run scripts/evaluate.py \
    --benchmark xbench \
    --predictions output/xbench_run/predictions.jsonl \
    --dataset dataset/XBENCH/DeepSearch-2510.json \
    --output-dir output/xbench_run/eval \
    --max-workers 30

# Evaluate FinSearchComp
uv run scripts/evaluate.py \
    --benchmark finsearchcomp \
    --predictions output/finsearch_run/predictions.jsonl \
    --dataset dataset/FinSearchComp/t2_t3_questions.json \
    --max-workers 30
```

--------------------------------

### Run Evolution Loop for HLE Dataset

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/docs/reproduce.md

Executes the evolution loop specifically for the HLE dataset. Uses the common configuration and the `evolve.sh` script with dataset and run name set to 'HLE'.

```bash
./scripts/evolve.sh --dataset HLE --run_name hle --batch_size 16
```

--------------------------------

### Evaluate Predictions for XBENCH-scienceqa

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/docs/reproduce.md

Evaluates predictions for the XBENCH-scienceqa dataset. Uses the `evaluate.py` script with benchmark set to 'xbench' and dataset path specific to XBENCH-scienceqa.

```bash
uv run scripts/evaluate.py --benchmark xbench --predictions output/xbench-scienceqa/predictions.jsonl --dataset dataset/XBENCH/ScienceQA.json --max-workers 30
```

--------------------------------

### Pydantic Input/Output Models (Python)

Source: https://github.com/yunjuetech/yunjue-agent/blob/main/src/prompts/templates/toolsmiths_agent.md

Illustrates the use of Pydantic `BaseModel` for defining input and output schemas. It emphasizes using `@field_validator` (with `mode='before'`) for validation, as required by Pydantic v2, and ensures output fields are LLM-friendly.

```python
from pydantic import BaseModel, Field, field_validator

class InputModel(BaseModel):
    # fields derived from input_schema (exact same names & inferred types)
    # Use @field_validator for field-level validation (Pydantic v2 syntax), the mode of field_validator must be 'before'.
    # DO NOT use @root_validator or @validator (deprecated)

class OutputModel(BaseModel):
    # fields derived from output_schema (exact same names & inferred types)
    # Use @field_validator for field-level validation (Pydantic v2 syntax), the mode of field_validator must be 'before'.
    # DO NOT use @root_validator or @validator (deprecated)
    # IMPORTANT: All output fields MUST be LLM-friendly (no raw HTML, no large binary data, only structured/parsed content)
```