Custom AI Engines | GitHub Agentic Workflows
Skip to main content Custom AI Engines Third-party coding agents integrate through a Markdown engine definition, maintained by the engine’s publisher. Its engine.behaviors frontmatter declares installation, configuration, execution, and log parsing. Importing the definition registers the engine at compile time without changing the gh-aw binary. For built-in engines and their feature matrix, see AI engines . Shared imported engines Section titled “Shared imported engines” Custom engines require object form with engine.id .
String form accepts only built-in IDs; there is no engine: custom . engine : id : example-engine imports : - owner/repository/.github/workflows/example-engine.md@v1.2.3 The ID must match the imported definition. Prefer a publisher-maintained definition pinned to a reviewed commit SHA or tag. Local definitions can be vendored under .github/workflows/shared/ and imported by path. An imported definition is executable configuration: review its installation commands, permissions, network access, secret handling, tool restrictions, and parser.
Compatibility and support belong to its publisher; gh-aw does not guarantee native-agent features or restrictions merely because a definition compiles. Agent Plugins are available only when the definition declares behaviors.plugins ; see plugin configuration . Authentication and inference Section titled “Authentication and inference” Credentials, model prefixes, and provider routing depend on the definition. Configure the secrets and network destinations it declares.
A custom engine can support multiple inference providers, but that does not imply compatibility with every provider API. safe-outputs.threat-detection: true uses Copilot by default, even when the main agent is custom. Supply Copilot authentication or choose a supported detection engine explicitly; see Threat detection . Unsupported engine samples Section titled “Unsupported engine samples” These definitions are examples for integration authors, not supported gh-aw engines .
They have no compatibility or maintenance commitment. Production users should obtain a definition maintained by the engine owner. Engine Sample definition OpenCode opencode.md Aider aider.md Crush crush.md Cursor cursor.md DeepSeek Harness deepseek-harness.md Factory Droid factory.md Goose goose.md Kiro kiro.md mini-SWE-agent mini-swe-agent.md Pydantic AI Publisher definition Sample-specific constraints Section titled “Sample-specific constraints” Sample Runtime and limitations OpenCode Installs OpenCode 2 from @opencode/cli , uses --standalone , native MCP with Code Mode disabled, and JSONL events.
Copilot requires AWF; direct Anthropic/OpenAI BYOK is supported without it. Repository JSON/JSONC settings are overlaid; updates/sharing are disabled. V2 has no language servers, and V1 plugins require porting. Native npm plugins are not gh-aw Agent Plugins. DeepSeek Harness Pins dsh v0.2.0-rc.2. Uses headless stdin prompts, a private per-run configuration patch, and CLI-proxy tools rather than native MCP. Copilot requires AWF; direct Anthropic/OpenAI credentials apply only without AWF.
Per-command native bash restrictions are rejected. No native reasoning, tool, refusal, or token-accounting observations are inferred from stdout. Factory Droid Pins @factory/cli 0.248.0 with lifecycle scripts disabled. Uses custom models through the AWF API proxy with placeholder credentials; real provider and Factory keys are excluded from the agent. Supports Copilot, Anthropic, and OpenAI inference, file-based prompts, high autonomy inside the sandbox, and native HTTP MCP.
Native MCP retains the gateway session authorization in agent-readable .factory/mcp.json ; this is not an upstream provider credential or a security boundary against the agent (see gateway authentication ). Removing it prevents authenticated MCP calls. No Factory API key is required. Factory-managed inference, direct-key execution, structured session parsing, gh-aw tool allowlists, max-turn enforcement, and Agent Plugins are unsupported.
Goose Pins CLI v1.53.0 with archive checksum verification. Uses OpenAI-compatible inference, native authenticated MCP, file-based prompts, and JSONL tool/usage events. Configuration/session state is temporary; keyring is disabled. No native gh-aw web-fetch ; use MCP or shell. Copilot can use copilot-requests: write without a PAT. Kiro Sample pins CLI 2.31.1 with the V2 harness; Powers plugins are not supported. mini-SWE-agent Pins PyPI 2.4.6 on Python 3.12.
Uses the non-interactive Python API, text-based shell actions, file-based prompts, and AWF-only Copilot, OpenAI/Codex, or Anthropic inference. Native task submission is required for success; max-turns limits model calls. Tools use CLI proxies, not native MCP. The untrusted native trajectory is retained in the unified agent artifact only after secret redaction and recovery-envelope validation, including failed executions.
No native shell allowlists, edit disabling, Agent Plugins, repository mini configuration, or structured session parser. Read the pinned definition for its exact install and provider contract. Native events and accounting are retained only when observed; process exit zero alone does not prove task completion. mini-SWE-agent package access Section titled “mini-SWE-agent package access” The mini-SWE sample downloads hash-locked binary wheels in trusted pre-agent-steps , before AWF starts.
Agent-time installation is isolated and offline; pip verifies the same hashes again. No dependencies are installed into the host user site. The shared import also declares runtimes.python , which explicitly grants the agent Python ecosystem access, including pypi.org and files.pythonhosted.org . Engine defaults do not grant this access. For registry-free execution, vendor the definition without runtimes , retain its bootstrap steps, and provide Python 3.12 on a Linux x86-64 runner independently.
Callers can opt back in with network.allowed: [python] or runtimes.python . Defining an engine Section titled “Defining an engine” A definition contains engine.id , metadata, and engine.behaviors . Its behaviors install the CLI, configure inference and MCP, invoke it headlessly, and expose logs for session reconstruction. Keep secrets outside the agent sandbox and fail explicitly when required credentials, endpoints, or restrictions cannot be honored.
Start from a sample with a matching transport rather than copying installation or configuration code into every workflow. Publish the definition with versioned changes and document its credentials, models, tool restrictions, supported platforms, and unified session coverage. See imports for resolution and pinning rules. Secret environment overrides Section titled “Secret environment overrides” An imported definition declares supported environment variable names in engine.behaviors.supported-env-var-keys .
In strict mode, these names are allowed to carry secret references in the consuming workflow’s engine.env . The compiler checks those overrides after resolving imports and registering the engine, so the imported definition’s allowlist applies. This does not permit arbitrary secret-bearing variables: undeclared keys in engine.env remain subject to strict-mode validation, and secret references in top-level env are still rejected.
In strict mode, secret overrides require AWF v0.25.3 or newer to exclude them from the agent container. See workflow environment variables for the restrictions on top-level env . Durable execution Section titled “Durable execution” A workflow can opt into artifact-backed continuation using engine.durable: { retention-days: 7 } alongside its custom engine.id . Compilation fails unless the definition declares behaviors.durable .
Engines that implement the Go interface provide GetDurableExecutionPlan with the files to persist and the continuation execution steps. An engine does not need a native durable library. It can declare its sess
The rest of this page is on the live site.