custom-engine-implementation

Custom Agentic Engine Implementation Guide

This document provides a comprehensive guide for implementing custom agentic engines in GitHub Agentic Workflows (gh-aw). It covers architecture patterns, common refactoring opportunities, and step-by-step implementation instructions.

Table of Contents

1. Architecture Overview
2. Engine Interface Design
3. Common Code Analysis & Refactoring Opportunities
4. Implementation Guide
5. Testing Strategy
6. Integration Checklist

---

Architecture Overview

Interface Segregation Principle

The agentic engine architecture follows the Interface Segregation Principle (ISP) to avoid forcing implementations to depend on methods they don't use. The system uses interface composition to provide flexibility while maintaining backward compatibility.

Interface Hierarchy

Engine (core identity - required by all)
├── GetID()
├── GetDisplayName()
├── GetDescription()
└── IsExperimental()

CapabilityProvider (feature detection - optional)
├── SupportsToolsAllowlist()
├── SupportsHTTPTransport()
├── SupportsMaxTurns()
├── SupportsWebFetch()
├── SupportsWebSearch()
├── SupportsFirewall()
├── SupportsPlugins()
└── SupportsLLMGateway()

WorkflowExecutor (compilation - required)
├── GetDeclaredOutputFiles()
├── GetInstallationSteps()
└── GetExecutionSteps()

MCPConfigProvider (MCP servers - optional)
└── RenderMCPConfig()

LogParser (log analysis - optional)
├── ParseLogMetrics()
├── GetLogParserScriptId()
└── GetLogFileForParsing()

SecurityProvider (security features - optional)
├── GetDefaultDetectionModel()
└── GetRequiredSecretNames()

CodingAgentEngine (composite - backward compatibility)
└── Composes all above interfaces

Key Architectural Patterns

1. BaseEngine Embedding: All engines embed BaseEngine which provides default implementations
2. Focused Interfaces: Each interface has a single responsibility
3. Optional Capabilities: Engines override only the methods they need
4. Backward Compatibility: CodingAgentEngine composite interface maintains compatibility