Build Tool-Calling and Self-Evolving LLM Agents with miniEvoAgent

What is miniEvoAgent?

miniEvoAgent is a compact Python framework for learning how LLM-based agents are constructed and improved. Inspired by EvoAgentX, it retains the core concepts of agent execution, tool calling, evaluation, prompt rewriting, and self-evolution while removing the complexity of a large agent framework.

The package is currently named evo_repro. Its intentionally small design makes each mechanism easier to read, test, and extend. Rather than providing workflow graphs, memory, visual editors, benchmark adapters, or a large tool ecosystem, it focuses on a transparent single-action agent and prompt evolution loop.

How the framework works

A miniEvoAgent application is assembled from a few focused components:

• PromptTemplate: Inserts task inputs into a prompt template.
• Action: Calls an LLM, optionally performs multi-round tool execution, and parses the final response.
• Agent: Wraps an action and returns a structured message.
• Evaluator functions: Score QA predictions with exact match, token-level F1, and accuracy.
• PromptRewriter: Uses an optimizer LLM to propose a revised prompt from concrete feedback examples.
• PromptSelector: compares a parent prompt with its candidate on the same development set and retains the better performer.
• evolve: Repeats training execution, feedback generation, rewriting, evaluation, and selection.

Key features

• A minimal, inspectable single-action agent abstraction.
• An OpenAI-compatible LLM adapter configured through environment variables or a local .env file.
• OpenAI-style function tools with multi-round tool execution.
• Feedback-driven prompt rewriting through an optimizer LLM.
• Development-set selection that accepts a candidate only when it improves the score.
• Evolution traces containing training executions, rewrite inputs, development scores, and selection decisions.
• Deterministic fake LLMs for testing framework behavior without remote API calls.

Install miniEvoAgent

Requirements

Use Python 3.10 or newer. The following PowerShell commands enter the repository, create a virtual environment, activate it, update pip, and install the package in editable mode:

cd D:\Projects\RSIProject\student-project\Evo-repro
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e .

Editable installation is useful while studying or modifying the source because local package changes are immediately available to your Python environment.

Configure an OpenAI-compatible LLM

The default OpenAILLM adapter reads its settings from environment variables or a local .env file. In PowerShell, set an API key and model as follows:

$env:OPENAI_API_KEY="your_api_key"
$env:OPENAI_MODEL="gpt-4o-mini"

If you use another OpenAI-compatible service, set its endpoint:

$env:OPENAI_BASE_URL="https://your-compatible-endpoint/v1"

Alternatively, copy .env.example to .env and add the same configuration values there.

Build a basic question-answering agent

A basic agent needs an LLM, a prompt template, an output parser, and an action. The agent then exposes these parts through a simple execution interface.

from evo_repro import Action, Agent, OpenAILLM, PromptTemplate, TextOutputParser

llm = OpenAILLM()

action = Action(
    name="answer_question",
    prompt_template=PromptTemplate(
        template="Answer the following question:\n\n{question}"
    ),
    llm=llm,
    output_parser=TextOutputParser(),
)

agent = Agent(
    name="qa_agent",
    description="Answers a single user question.",
    action=action,
)

message = agent.execute({
    "question": "What is Retrieval-Augmented Generation?"
})
print(message.content)

The question key supplied to agent.execute corresponds to the {question} placeholder in the template. The action renders the prompt, sends it to the configured LLM, parses the returned text, and wraps the result in a structured message.

You can also run the bundled example:

python examples\simple_agent.py

Add a callable Python tool

miniEvoAgent tools are thin wrappers around Python functions. Each tool provides a JSON schema that the model can use for function calling and returns a structured ToolResult.

The package includes get_word_length_tool, which can be attached to an action through its tools argument:

from evo_repro import Action, Agent, OpenAILLM, PromptTemplate, TextOutputParser
from evo_repro import get_word_length_tool

agent = Agent(
    name="tool_agent",
    description="Answers a question and can use tools.",
    action=Action(
        name="answer_with_tools",
        prompt_template=PromptTemplate(
            template=(
                "Answer the following question. "
                "Use tools when useful:\n\n{question}"
            )
        ),
        llm=OpenAILLM(),
        output_parser=TextOutputParser(),
        tools=[get_word_length_tool],
    ),
)

message = agent.execute({
    "question": 'How many characters are in "retrieval"?'
})

print(message.content)
print(message.metadata["tool_results"])

When the LLM requests a supported function, the action executes it and returns the tool result to the conversation. The action supports multiple rounds of this process before parsing the final model output. Tool execution records are available through message.metadata["tool_results"].

Run the included tool example with:

python examples\tool_agent.py

Understand prompt self-evolution

The self-evolution system improves a prompt through a controlled feedback and evaluation cycle:

1. Run the current prompt on training examples.
2. Turn predictions, expected labels, and evaluation metrics into feedback examples.
3. Ask a PromptRewriter backed by an optimizer LLM to generate one candidate prompt.
4. Evaluate both the parent and candidate prompts on the same development set.
5. Use PromptSelector to retain the better prompt.
6. Repeat the process for the configured number of generations.

Use evolve_once(...) when you want to run one generation. It returns an EvolutionRoundTrace. Use evolve(...) to run multiple generations and receive both the final prompt and the complete history.

Audit evolution without a remote model

The repository includes a deterministic audit example that uses fake LLM behavior:

python examples\evolution_audit.py

The output shows each generation's parent prompt, training records, rewrite input, candidate prompt, development-set comparison, and acceptance or rejection decision. This makes it possible to inspect the optimization process rather than treating prompt improvement as a hidden operation.

Evaluate QA predictions

The built-in evaluators provide three intentionally simple QA metrics:

• Exact match: Checks whether the prediction matches the expected answer exactly under the evaluator's comparison behavior.
• Token-level F1: Measures token overlap between the prediction and expected answer.
• Accuracy: Reports the proportion of correct predictions.

These metrics are designed to verify and demonstrate the evolution loop. The project notes that they can later be replaced with evaluators suited to a specific benchmark or task.

Run the test suite

Execute all tests from the repository root:

python -m pytest

The focused test suite covers agents, tools, and evolution behavior. Fake LLM implementations are used where possible, so most framework logic can be verified without an API key or remote model call.

Advanced tips

Use deterministic tests before live experiments

Start with the fake LLM examples and tests when changing prompt selection, tool handling, or evolution logic. Deterministic outputs make failures reproducible and help separate framework bugs from variation in live model responses.

Inspect traces at every generation

Do not evaluate an evolution run only by its final prompt. Review the recorded training executions, feedback supplied to the rewriter, candidate prompt, development scores, and selection decision. These records reveal why a candidate was accepted or rejected.

Keep training and development roles distinct

The evolution process creates rewrite feedback from training examples but compares the parent and candidate on the same development set. Preserve this division when preparing experiments so that selection follows the framework's intended process.

Inspect structured tool results

For tool-enabled agents, examine message.metadata["tool_results"] as well as the final text. This helps verify whether the model selected a tool, whether execution succeeded, and what structured result was returned.

Use a compatible custom endpoint when needed

The OPENAI_BASE_URL setting allows OpenAILLM to target an OpenAI-compatible endpoint. Keep the API key and selected model aligned with the endpoint's requirements.

Understand the project's current scope

miniEvoAgent is deliberately narrower than EvoAgentX. It does not currently claim workflow graphs, multi-agent orchestration, memory, human-in-the-loop features, benchmark integration, visual editing, or broad toolkits. The roadmap includes richer workflow composition, more provider adapters, benchmark loaders, reusable toolkits, JSON persistence, and additional documentation, but these are planned rather than current features.

Check licensing before redistribution

No license file is currently included in the project. Add an appropriate license before publishing or redistributing the code.

Conclusion

miniEvoAgent provides a small, testable path into LLM agent engineering. With the evo_repro package, you can construct a prompt-driven agent, add OpenAI-style function tools, measure QA performance, rewrite prompts from failures, and retain improvements through development-set evaluation. Its compact architecture and deterministic examples make it especially useful for studying how agent execution and prompt evolution work internally.