Codex SDK Research Agent Design

Goal

Adapt the project-scoped kompas-sdk-research custom agent for Codex while leaving the Claude Code agent unchanged. The Codex agent must be optimized for fast, read-heavy searches in the local KOMPAS SDK Markdown knowledge base and must not modify the workspace.

Configuration

The Codex agent remains in .codex/agents/kompas-sdk-research.toml and uses:

name = "kompas-sdk-research"
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"

gpt-5.6-terra fits exploration, documentation scans, and distilled support work. Medium reasoning is used because SDK questions can require correlating several interfaces, overloads, constants, and COM call-chain details.

Agent Responsibilities

The agent searches only local project and installed SDK reference material:

docs/Kompas3D_SDK/ is the canonical source for COM API5/API7 documentation.
SDK headers under the installed KOMPAS SDK may be read when exact constant values need confirmation.
The agent must not browse the web, edit files, implement features, or build geometry in KOMPAS-3D.
KsAPI is outside the Markdown knowledge base and must be reported as outside scope instead of guessed.

The parent agent delegates non-trivial SDK lookups before implementation. It remains responsible for validating interop-specific discrepancies through reflection over libs/kompas-interop/*.dll when needed.

Prompt Adaptation

Remove Claude-specific references to Haiku and Opus from the Codex TOML. Keep the existing domain guidance, but express it in provider-neutral Codex terms. The description must make proactive delegation triggers clear without claiming that the agent uses tools or model behavior specific to Claude Code.

The response contract remains concise and evidence-oriented:

Relevant interface, method, property, enum, or constant.
Automation syntax and COM syntax when parameter ordering matters.
Parameter and return-value meanings, including units and side effects.
Related overloads or interfaces when relevant.
Source article path and its sources frontmatter entry.
A warning when generated .NET interop names may differ from SDK docs.

Isolation and Compatibility

The Claude definition in .claude/agents/kompas-sdk-research.md is not changed. The two versions intentionally use different configuration formats and model selection while sharing the same research methodology.

The Codex agent's read-only behavior is enforced by sandbox_mode, not merely requested in prose. No exact Claude-style tool allowlist is copied into the Codex configuration.

Verification

After editing the TOML:

parse it as TOML;
confirm the required fields and selected model settings;
confirm sandbox_mode = "read-only";
search the Codex file for stale Haiku, Opus, and Claude-specific wording;
confirm the Claude agent file is unchanged.

2.9 KiB Raw Blame History