autonomous-agent-patterns

# 🕹️ Autonomous Agent Patterns > Design patterns for building autonomous coding agents, inspired by [Cline](https://github.com/cline/cline) and [OpenAI Codex](https://github.com/openai/codex). ## When to Use This Skill Use this skill when: - Building autonomous AI agents - Designing tool/function calling APIs - Implementing permission and approval systems - Creating browser automation for agents - Designing human-in-the-loop workflows --- ## 1. Core Agent Architecture ### 1.1 Agent Loop ``` ┌─────────────────────────────────────────────────────────────┐ │ AGENT LOOP │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Think │───▶│ Decide │───▶│ Act │ │ │ │ (Reason) │ │ (Plan) │ │ (Execute)│ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ ▲ │ │ │ │ ┌──────────┐ │ │ │ └─────────│ Observe │◀─────────┘ │ │ │ (Result) │ │ │ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ```python class AgentLoop: def __init__(self, llm, tools, max_iterations=50): self.llm = llm self.tools = {t.name: t for t in tools} self.max_iterations = max_iterations self.history = [] def run(self, task: str) -> str: self.history.append({"role": "user", "content": task}) for i in range(self.max_iterations): # Think: Get LLM response with tool options response = self.llm.chat( messages=self.history, tools=self._format_tools(), tool_choice="auto" ) # Decide: Check if agent wants to use a tool if response.tool_calls: for tool_call in response.tool_calls: # Act: Execute the tool result = self._execute_tool(tool_call) # Observe: Add result to history self.history.append({ "role": "tool", "tool_call_id": tool_call.id, "content": str(result) }) else: # No more tool calls = task complete return response.content return "Max iterations reached" def _execute_tool(self, tool_call) -> Any: tool = self.tools[tool_call.name] args = json.loads(tool_call.arguments) return tool.execute(**args) ``` ### 1.2 Multi-Model Architecture ```python class MultiModelAgent: """ Use different models for different purposes: - Fast model for planning - Powerful model for complex reasoning - Specialized model for code generation """ def __init__(self): self.models = { "fast": "gpt-3.5-turbo", # Quick decisions "smart": "gpt-4-turbo", # Complex reasoning "code": "claude-3-sonnet", # Code generation } def select_model(self, task_type: str) -> str: if task_type == "planning": return self.models["fast"] elif task_type == "analysis": return self.models["smart"] elif task_type == "code": return self.models["code"] return self.models["smart"] ``` --- ## 2. Tool Design Patterns ### 2.1 Tool Schema ```python class Tool: """Base class for agent tools""" @property def schema(self) -> dict: """JSON Schema for the tool""" return { "name": self.name, "description": self.description, "parameters": { "type": "object", "properties": self._get_parameters(), "required": self._get_required() } } def execute(self, **kwargs) -> ToolResult: """Execute the tool and return result""" raise NotImplementedError class ReadFileTool(Tool): name = "read_file" description = "Read the contents of a file from the filesystem" def _get_parameters(self): return { "path": { "type": "string", "description": "Absolute path to the file" }, "start_line": { "type": "integer", "description": "Line to start reading from (1-indexed)" }, "end_line": { "type": "integer", "description": "Line to stop reading at (inclusive)" } } def _get_required(self): return ["path"] def execute(self, path: str, start_line: int = None, end_line: int = None) -> ToolResult: try: with open(path, 'r') as f: lines = f.readlines() if start_line and end_line: lines = lines[start_line-1:end_line] return ToolResult( success=True, output="".join(lines) ) except FileNotFoundError: return ToolResult( success=False, error=f"File not found: {path}" ) ``` ### 2.2 Essential Agent Tools ```python CODING_AGENT_TOOLS = { # File operations "read_file": "Read file contents", "write_file": "Create or overwrite a file", "edit_file": "Make targeted edits to a file", "list_directory": "List files and folders", "search_files": "Search for files by pattern", # Code understanding "search_code": "Search for code patterns (grep)", "get_definition": "Find function/class definition", "get_references": "Find all references to a symbol", # Terminal "run_command": "Execute a shell command", "read_output": "Read command output", "send_input": "Send input to running command", # Browser (optional) "open_browser": "Open URL in browser", "click_element": "Click on page element", "type_text": "Type text into input", "screenshot": "Capture screenshot", # Context "ask_user": "Ask the user a question", "search_web": "Search the web for information" } ``` ### 2.3 Edit Tool Design ```python class EditFileTool(Tool): """ Precise file editing with conflict detection. Uses search/replace pattern for reliable edits. """ name = "edit_file" description = "Edit a file by replacing specific content" def execute( self, path: str, search: str, replace: str, expected_occurrences: int = 1 ) -> ToolResult: """ Args: path: File to edit search: Exact text to find (must match exactly, including whitespace) replace: Text to replace with expected_occurrences: How many times search should appear (validation) """ with open(path, 'r') as f: content = f.read() # Validate actual_occurrences = content.count(search) if actual_occurrences != expected_occurrences: return ToolResult( success=False, error=f"Expected {expected_occurrences} occurrences, found {actual_occurrences}" ) if actual_occurrences == 0: return ToolResult( success=False, error="Search text not found in file" ) # Apply edit new_content = content.replace(search, replace) with open(path, 'w') as f: f.write(new_content) return ToolResult( success=True, output=f"Replaced {actual_occurrences} occurrence(s)" ) ``` --- ## 3. Permission & Safety Patterns ### 3.1 Permission Levels ```python class PermissionLevel(Enum): # Fully automatic - no user approval needed AUTO = "auto" # Ask once per session ASK_ONCE = "ask_once" # Ask every time ASK_EACH = "ask_each" # Never allow NEVER = "never" PERMISSION_CONFIG = { # Low risk - can auto-approve "read_file": PermissionLevel.AUTO, "list_directory": PermissionLevel.AUTO, "search_code": PermissionLevel.AUTO, # Medium risk - ask once "write_file": PermissionLevel.ASK_ONCE, "edit_file": PermissionLevel.ASK_ONCE, # High risk - ask each time "run_command": PermissionLevel.ASK_EACH, "delete_file": PermissionLevel.ASK_EACH, # Dangerous - never auto-approve "sudo_command": PermissionLevel.NEVER, "format_disk": PermissionLevel.NEVER } ``` ### 3.2 Approval UI Pattern ```python class ApprovalManager: def __init__(self, ui, config): self.ui = ui self.config = config self.session_approvals = {} def request_approval(self, tool_name: str, args: dict) -> bool: level = self.config.get(tool_name, PermissionLevel.ASK_EACH) if level == PermissionLevel.AUTO: return True if level == PermissionLevel.NEVER: self.ui.show_error(f"Tool '{tool_name}' is not allowed") return False if level == PermissionLevel.ASK_ONCE: if tool_name in self.session_approvals: return self.session_approvals[tool_name] # Show approval dialog approved = self.ui.show_approval_dialog( tool=tool_name, args=args, risk_level=self._assess_risk(tool_name, args) ) if level == PermissionLevel.ASK_ONCE: self.session_approvals[tool_name] = approved return approved def _assess_risk(self, tool_name: str, args: dict) -> str: """Analyze specific call for risk level""" if tool_name == "run_command": cmd = args.get("command", "") if any(danger in cmd for danger in ["rm -rf", "sudo", "chmod"]): return "HIGH" return "MEDIUM" ``` ### 3.3 Sandboxing ```python class SandboxedExecution: """ Execute code/commands in isolated environment """ def __init__(self, workspace_dir: str): self.workspace = workspace_dir self.allowed_commands = ["npm", "python", "node", "git", "ls", "cat"] self.blocked_paths = ["/etc", "/usr", "/bin", os.path.expanduser("~")] def validate_path(self, path: str) -> bool: """Ensure path is within workspace""" real_path = os.path.realpath(path) workspace_real = os.path.realpath(self.workspace) return real_path.startswith(workspace_real) def validate_command(self, command: str) -> bool: """Check if command is allowed""" cmd_parts = shlex.split(command) if not cmd_parts: return False base_cmd = cmd_parts[0] return base_cmd in self.allowed_commands def execute_sandboxed(self, command: str) -> ToolResult: if not self.validate_command(command): return ToolResult( success=False, error=f"Command not allowed: {command}" ) # Execute in isolated environment result = subprocess.run( command, shell=True, cwd=self.workspace, capture_output=True, timeout=30, env={ **os.environ, "HOME": self.workspace, # Isolate home directory } ) return ToolResult( success=result.returncode == 0, output=result.stdout.decode(), error=result.stderr.decode() if result.returncode != 0 else None ) ``` --- ## 4. Browser Automation ### 4.1 Browser Tool Pattern ```python class BrowserTool: """ Browser automation for agents using Playwright/Puppeteer. Enables visual debugging and web testing. """ def __init__(self, headless: bool = True): self.browser = None self.page = None self.headless = headless async def open_url(self, url: str) -> ToolResult: """Navigate to URL and return page info""" if not self.browser: self.browser = await playwright.chromium.launch(headless=self.headless) self.page = await self.browser.new_page() await self.page.goto(url) # Capture state screenshot = await self.page.screenshot(type='png') title = await self.page.title() return ToolResult( success=True, output=f"Loaded: {title}", metadata={ "screenshot": base64.b64encode(screenshot).decode(), "url": self.page.url } ) async def click(self, selector: str) -> ToolResult: """Click on an element""" try: await self.page.click(selector, timeout=5000) await self.page.wait_for_load_state("networkidle") screenshot = await self.page.screenshot() return ToolResult( success=True, output=f"Clicked: {selector}", metadata={"screenshot": base64.b64encode(screenshot).decode()} ) except TimeoutError: return ToolResult( success=False, error=f"Element not found: {selector}" ) async def type_text(self, selector: str, text: str) -> ToolResult: """Type text into an input""" await self.page.fill(selector, text)