README.md

---
license: agpl-3.0
language:
- en
base_model:
- Qwen/Qwen3-Coder-30B-A3B-Instruct
---

# Coding agent

A simple coding agent built with Qwen_Distilled_Coder (via OpenRouter) that can view/edit files and execute bash commands—all in ~200 lines.


```mermaid
flowchart TD
   Start([Start]) --> UserInput[Get User Input]
   UserInput --> Qwen_Distilled_Coder[Send to Qwen_Distilled_Coder]
   Qwen_Distilled_Coder --> NeedsTools{Needs Tools?}

   NeedsTools -->|No| ShowResponse[Show Response]
   NeedsTools -->|Yes| ExecuteTools[Execute Tools]

   ExecuteTools --> SendResults[Send Results to Qwen_Distilled_Coder]
   SendResults --> Qwen_Distilled_Coder

   ShowResponse --> UserInput

   ExecuteTools -.-> Tools
```

## Quick start

1. **Create virtual environment and install dependencies**:

   ```bash
   # Option 1: uv installed
   uv venv
   source .venv/bin/activate # On Windows: .venv\Scripts\activate
   uv sync

   # Option 2: Without uv
   python3 -m venv .venv
   source .venv/bin/activate # On Windows: .venv\Scripts\activate
   pip3 install uv
   uv sync
   ```

2. **Setup environment & add API key**:

   ```bash
   cp .env.example .env
   ```

   Be sure to add your OpenRouter API key! You can get one from [OpenRouter](https://openrouter.ai/keys).

3. **Run the CLI agent**:

   ```bash
   uv run simple_agent.py
   ```


Note: `uv` and an appropriate virtualenv are prerequisites—our agent will use uv to execute Python scripts

## Using OpenRouter with Qwen Distilled Coder

This agent uses the [OpenRouter](https://openrouter.ai/) API to access the Qwen_Distilled_Coder model. OpenRouter provides a unified API for accessing various AI models, including those from Anthropic, OpenAI, and others.

To use this agent:

1. Sign up for an account at [OpenRouter](https://openrouter.ai/)
2. Create an API key at [OpenRouter Keys](https://openrouter.ai/keys)
3. Add your API key to the `.env` file
4. Run the agent with `uv run simple_agent.py`

The agent uses the OpenAI client library but points it to the OpenRouter API endpoint, allowing it to access the Qwen_Distilled_Coder model.

## What it does

- **Fix broken files**: `"can you help me fix broken_file.py?"`
- **Research and implement**: `"research new Python 3.13 features and write a file that demonstrates a simple example"`
- **Create new code**: `"write a simple tip splitting calculator Python file"`

## Architecture

The agent follows a straightforward pattern with three core components:

### Prompt structure

```xml
<role>
You are an expert software engineering assistant...
</role>

<thinking_process>
Before taking any action, think through the problem step by step...
</thinking_process>

<instructions>
When working with code:
1. Understanding First: Always examine existing files...
2. Targeted Changes: Use precise `str_replace` operations...
</instructions>
```

**Best practices:**

- Split system prompt (role) from user instructions for better caching
- Use XML tags for structured prompts and interpretability  
- Include chain-of-thought reasoning with `<thinking_process>` blocks
- Cache tools, system prompt, and first user message for cost optimization

### Tool execution router

```python
def execute_tool(tool_name: str, tool_input: dict) -> dict:
    """Execute a tool and return structured result with error handling."""
    try:
        if tool_name == "view":
            # Handle file/directory viewing
        elif tool_name == "str_replace":
            # Handle targeted file edits
        elif tool_name == "bash":
            # Handle command execution with timeout
        # ...
    except Exception as e:
        return {"content": f"Error: {str(e)}", "is_error": True}
```

**Best practices:**

- Return structured responses with `is_error` flag for Qwen_Distilled_Coder
- Use proper timeout protection (30s default for bash)
- Include detailed error logging and handling
- Support both file operations and bash commands

### Agent loop

```python
while True:
    response = client.messages.create(
        model=ANTHROPIC_MODEL,
        system=[{"type": "text", "text": system_prompt}],
        messages=messages,
        tools=ANTHROPIC_TOOLS,
    )
    
    if response.stop_reason == "tool_use":
        # Execute tools in parallel when possible
        # Return results to Qwen_Distilled_Coder for continued processing
    else:
        # Handle final response
        break
```

**Best practices:**

- Handle all stop reasons robustly (tool_use, end_turn, etc.)
- Execute multiple tools in parallel when possible
- Maintain conversation state through message history
- Use low temperature (0.2) for consistent, focused responses

## Files

- `simple_agent.py` - CLI version
- `prompt.md` - System prompt and instructions

## Requirements

- Python 3.13+
- OpenRouter API key