| name | autonomous-agent-patterns |
| description | Design patterns for building autonomous coding agents. Covers tool integration, permission systems, browser automation, and human-in-the-loop workflows. Use when building AI agents, designing tool APIs, implementing permission systems, or creating autonomous coding assistants. |
🕹️ Autonomous Agent Patterns
Design patterns for building autonomous coding agents, inspired by Cline and 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) │ │
│ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
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):
response = self.llm.chat(
messages=self.history,
tools=self._format_tools(),
tool_choice="auto"
)
if response.tool_calls:
for tool_call in response.tool_calls:
result = self._execute_tool(tool_call)
self.history.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": str(result)
})
else:
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
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",
"smart": "gpt-4-turbo",
"code": "claude-3-sonnet",
}
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
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)"
},
: {
: ,
:
}
}
():
[]
() -> ToolResult:
:
(path, ) f:
lines = f.readlines()
start_line end_line:
lines = lines[start_line-:end_line]
ToolResult(
success=,
output=.join(lines)
)
FileNotFoundError:
ToolResult(
success=,
error=
)
2.2 Essential Agent Tools
CODING_AGENT_TOOLS = {
"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",
"search_code": "Search for code patterns (grep)",
"get_definition": "Find function/class definition",
"get_references": "Find all references to a symbol",
"run_command": "Execute a shell command",
"read_output": "Read command output",
"send_input": "Send input to running command",
"open_browser": "Open URL in browser",
"click_element": "Click on page element",
"type_text": "Type text into input",
"screenshot": "Capture screenshot",
"ask_user": "Ask the user a question",
"search_web": "Search the web for information"
}
2.3 Edit Tool Design
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()
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"
)
new_content = content.replace(search, replace)
with open(path, 'w') as f:
f.write(new_content)
return ToolResult(
success=,
output=
)
3. Permission & Safety Patterns
3.1 Permission Levels
class PermissionLevel(Enum):
AUTO = "auto"
ASK_ONCE = "ask_once"
ASK_EACH = "ask_each"
NEVER = "never"
PERMISSION_CONFIG = {
"read_file": PermissionLevel.AUTO,
"list_directory": PermissionLevel.AUTO,
"search_code": PermissionLevel.AUTO,
"write_file": PermissionLevel.ASK_ONCE,
"edit_file": PermissionLevel.ASK_ONCE,
"run_command": PermissionLevel.ASK_EACH,
"delete_file": PermissionLevel.ASK_EACH,
"sudo_command": PermissionLevel.NEVER,
"format_disk": PermissionLevel.NEVER
}
3.2 Approval UI Pattern
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]
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:
tool_name == :
cmd = args.get(, )
(danger cmd danger [, , ]):
3.3 Sandboxing
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:
.validate_command(command):
ToolResult(
success=,
error=
)
result = subprocess.run(
command,
shell=,
cwd=.workspace,
capture_output=,
timeout=,
env={
**os.environ,
: .workspace,
}
)
ToolResult(
success=result.returncode == ,
output=result.stdout.decode(),
error=result.stderr.decode() result.returncode !=
)
4. Browser Automation
4.1 Browser Tool Pattern
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)
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
}
)
() -> ToolResult:
:
.page.click(selector, timeout=)
.page.wait_for_load_state()
screenshot = .page.screenshot()
ToolResult(
success=,
output=,
metadata={: base64.b64encode(screenshot).decode()}
)
TimeoutError:
ToolResult(
success=,
error=
)
() -> ToolResult:
.page.fill(selector, text)
ToolResult(success=, output=)
() -> ToolResult:
content = .page.evaluate()
ToolResult(success=, output=content)
4.2 Visual Agent Pattern
class VisualAgent:
"""
Agent that uses screenshots to understand web pages.
Can identify elements visually without selectors.
"""
def __init__(self, llm, browser):
self.llm = llm
self.browser = browser
async def describe_page(self) -> str:
"""Use vision model to describe current page"""
screenshot = await self.browser.screenshot()
response = self.llm.chat([
{
"role": "user",
"content": [
{"type": "text", "text": "Describe this webpage. List all interactive elements you see."},
{"type": "image", "data": screenshot}
]
}
])
return response.content
async def find_and_click(self, description: str) -> ToolResult:
"""Find element by visual description and click it"""
screenshot = await self.browser.screenshot()
response = self.llm.chat([
{
"role": "user",
"content": [
{
: ,
:
},
{: , : screenshot}
]
}
])
coords = json.loads(response.content)
.browser.page.mouse.click(coords[], coords[])
ToolResult(success=, output=)
5. Context Management
5.1 Context Injection Patterns
class ContextManager:
"""
Manage context provided to the agent.
Inspired by Cline's @-mention patterns.
"""
def __init__(self, workspace: str):
self.workspace = workspace
self.context = []
def add_file(self, path: str) -> None:
"""@file - Add file contents to context"""
with open(path, 'r') as f:
content = f.read()
self.context.append({
"type": "file",
"path": path,
"content": content
})
def add_folder(self, path: str, max_files: int = 20) -> None:
"""@folder - Add all files in folder"""
for root, dirs, files in os.walk(path):
for file in files[:max_files]:
file_path = os.path.join(root, file)
self.add_file(file_path)
def add_url(self, url: str) -> None:
"""@url - Fetch and add URL content"""
response = requests.get(url)
content = html_to_markdown(response.text)
self.context.append({
: ,
: url,
: content
})
() -> :
.context.append({
: ,
: diagnostics
})
() -> :
parts = []
item .context:
item[] == :
parts.append()
item[] == :
parts.append()
item[] == :
parts.append()
.join(parts)
5.2 Checkpoint/Resume
class CheckpointManager:
"""
Save and restore agent state for long-running tasks.
"""
def __init__(self, storage_dir: str):
self.storage_dir = storage_dir
os.makedirs(storage_dir, exist_ok=True)
def save_checkpoint(self, session_id: str, state: dict) -> str:
"""Save current agent state"""
checkpoint = {
"timestamp": datetime.now().isoformat(),
"session_id": session_id,
"history": state["history"],
"context": state["context"],
"workspace_state": self._capture_workspace(state["workspace"]),
"metadata": state.get("metadata", {})
}
path = os.path.join(self.storage_dir, f"{session_id}.json")
with open(path, 'w') as f:
json.dump(checkpoint, f, indent=2)
return path
def restore_checkpoint(self, checkpoint_path: str) -> dict:
"""Restore agent state from checkpoint"""
with open(checkpoint_path, 'r') f:
checkpoint = json.load(f)
{
: checkpoint[],
: checkpoint[],
: ._restore_workspace(checkpoint[]),
: checkpoint[]
}
() -> :
{
: subprocess.getoutput(),
: subprocess.getoutput()
}
6. MCP (Model Context Protocol) Integration
6.1 MCP Server Pattern
from mcp import Server, Tool
class MCPAgent:
"""
Agent that can dynamically discover and use MCP tools.
'Add a tool that...' pattern from Cline.
"""
def __init__(self, llm):
self.llm = llm
self.mcp_servers = {}
self.available_tools = {}
def connect_server(self, name: str, config: dict) -> None:
"""Connect to an MCP server"""
server = Server(config)
self.mcp_servers[name] = server
tools = server.list_tools()
for tool in tools:
self.available_tools[tool.name] = {
"server": name,
"schema": tool.schema
}
async def create_tool(self, description: str) -> str:
"""
Create a new MCP server based on user description.
'Add a tool that fetches Jira tickets'
"""
code = self.llm.generate(f"""
Create a Python MCP server with a tool that does:
{description}
Use the FastMCP framework. Include proper error handling.
Return only the Python code.
""")
server_name = self._extract_name(description)
path =
(path, ) f:
f.write(code)
.connect_server(server_name, {: path})
Best Practices Checklist
Agent Design
Safety
UX
Resources
