AI Engines | GitHub Agentic Workflows
Skip to main content AI Engines An engine runs a workflow’s Markdown instructions with its configured tools, sandbox, and safe outputs. This page covers selection and shared settings; engine-specific settings are in the individual references. Built-in AI engines Section titled “Built-in AI engines” Engine Selection Get started Technical reference GitHub Copilot (default) engine: copilot or omit engine Copilot setup Copilot reference Claude Code engine: claude Claude setup Claude reference OpenAI Codex engine: codex Codex setup Codex reference Gemini CLI (deprecated) engine: gemini Gemini setup Gemini reference Pi engine: pi Pi setup Pi reference Agy (experimental) engine: agy Agy setup Agy reference For imported engine definitions and third-party samples, see Custom AI engines .
Switching engines may require different credentials, models, tools, and network rules. Data handling before setup Section titled “Data handling before setup” The engine, inference provider, and enabled tools determine where repository context is processed. Before enabling a workflow, review provider terms, retention, accessible content, outbound destinations, and artifact access. Credentials are covered in Authentication .
Engine Feature Comparison Section titled “Engine Feature Comparison” Feature Copilot Claude Codex Gemini Pi Agy Top-level max-turns Yes Yes Yes Yes Yes No max-continuations Yes No No No No No tools.web-fetch SDK only Anthropic only Yes Yes Yes Cannot disable Native tools.web-search No Anthropic only Yes No No Cannot disable Native engine.agent selection Yes No No No No No engine.api-target Yes Yes Yes Yes Yes No engine.bare Yes Yes No No Yes No Custom engine.harness Yes Yes Yes No No No Per-command bash allowlist Yes Yes No Yes Yes No Native MCP Yes Yes Yes Yes Yes Production-conformance gated Agent Plugins ( plugins ) Yes Yes Yes No No No Artifact-backed engine.durable Session (CLI/SDK) Session Session Session Session (CLI/SDK/RPC) Session Codex can disable shell execution but cannot enforce a command allowlist.
Agy rejects unsupported tool restrictions rather than ignoring them. See individual references for provider-specific web access, bare-mode behavior, and dynamic workflows. max-turns defaults to 500 (legacy alias max-runs ); max-ai-credits defaults to 1000 . These are top-level fields, not engine properties. Agy supports credit/cache-miss limits but not max-turns . engine.max-turns is a deprecated Claude-only iteration limit.
Agent Plugins remain experimental. Extended Coding Agent Configuration Section titled “Extended Coding Agent Configuration” String form selects a built-in engine. Object form adds settings: engine : id : copilot model : opus env : DEBUG_MODE : " true " Field Contract id Built-in ID, or the ID of an imported definition . model Exact model ID, alias, or provider-prefixed selection; may also be top-level model . version Override the compiler-pinned CLI version. cooldown Minimum release age in nonnegative integer days; defaults to 3 .
Explicit 0 is rejected in strict mode. env Engine-only runtime values; use top-level env for all steps. Scope and precedence apply. args Ordered native CLI arguments placed before the prompt. Agy rejects it. command Replacement executable that skips the engine installer, not AWF installation. Provision it in setup steps; Agy checks the verified version, and Copilot checksum pins cannot be combined with it. api-target Endpoint hostname, where supported; see below. harness Replacement wrapper or retry settings for Copilot, Claude, and Codex. durable Artifact-backed session continuation with optional retention-days (1–90, default 7 ).
Engine-specific options such as agent , copilot-sdk , driver , dynamic-workflows , permission-mode , config , and extensions are documented in each engine reference. Agy rejects most overrides. Durable runs Section titled “Durable runs” All built-in engines support artifact-backed continuation: engine: id: copilot durable: retention-days: 7 The compiler restores an explicit parent from aw_context , or otherwise the last successful run of the same workflow on the same branch.
Reruns prefer a checkpoint from an earlier attempt of the same run. Retention follows repository and organization policy. Durable mode needs no memory tool and never dispatches another run. Engine Persisted state Continuation Copilot CLI and SDK Native session-state files and exact session ID CLI --session-id ; SDK resumeSession Claude Project transcripts, task state, and exact session ID CLI --resume <id> Codex Native and archived rollout sessions and exact thread ID CLI exec resume <id> Gemini Native temporary session storage and project registry Prompt points to restored session files Agy Native conversation databases Prompt points to restored session files Pi CLI, SDK and RPC Native JSONL conversation session CLI/RPC --session ; SDK SessionManager.open Copilot, Claude, Codex, and Pi resume the exact recorded session with the current prompt, credentials, models, and tool policy.
Gemini and Agy receive restoration metadata instead of a forced continuation argument. Restored history counts as metadata unless facts are verified against trusted sources, and restored text is never treated as an instruction. Durable mode reuses potentially attacker-influenced history across runs. The untrusted-data guidance is advisory, not enforced isolation, and does not eliminate cross-run prompt injection. Only session files are restored, not workspace edits, credentials, pending task phases, or exactly-once tool execution.
Restored Copilot events are excluded from current-run capture and model verification. With no prior run or checkpoint, the first run starts a new session. Missing explicit-parent artifacts, corrupt sessions, and authorization failures remain errors; they never silently start an unrelated conversation. The unified session records durable.restore ( restored , fresh , or failed ) and, for Copilot, Claude, Codex, and Pi, durable.session ( resumed or fresh ).
These records hold metadata only, and restoration alone does not prove native continuation for Gemini, Agy, or imported engines. Recording is best effort; missing records mean evidence is unavailable, not a fresh start or a failed restore. gh aw audit RUN --artifacts info,usage --json and gh aw health WORKFLOW --json --logs-dir DIRECTORY report this evidence; see the audit reference . Spans and durable session logs carry the checkpoint parent as gh-aw.durable.parent_run_id ; fresh runs omit it.
Built-in durable mode rejects replacement commands, custom drivers, and harnesses. Pi’s SDK and RPC drivers remain supported. Ordinary CLI arguments work, but session selectors and persistence-disabling flags cannot override compiler-managed continuation. Copilot cannot override COPILOT_HOME . Pi has additional restrictions , and imported engines must declare their own durable files. Threat detection uses a separate fresh session.
Checkpoints are published after secret redaction and integrity validation. Cancellation or hard runner loss can prevent publication. Artifacts contain restorable session content that may expose sensitive history to anyone with artifact access, and redaction is heuristic. Enable durable mode only where that suits the repository’s artifact access and retention policies. Pinning a Specific Engine Version Section titled “Pinning a Specific Engine Version” The compiler pins a CLI release.
Override it with engine.version , then recompile: engine : id : copilot version : " 1.0.101 " Versions may use Actions expressions, passed through environment variables rather than shell interpolation. Copilot expressions must resolve to trusted cached releases or built-in manifest pins; other Copilot releases need a literal version and a checksum pin . Agy accepts only verified releases. Engine release-age cooldown Section titled “Engine release-age cooldown” Compiler-managed engine installs use a 3-day minimum rel
The rest of this page is on the live site.