Agent Configurations

akms.orchestrator.agent_configs

agent_configs.py — Per-Role Agent Configurations (§3 of system design).

Defines the configuration and behavior profiles for different agent roles within the AKMS orchestrator pipeline.

Three primary roles: - Implementer: Standard tools + AKMS loadout for task execution - Code Reviewer: Phase diffs + search_mirror.qmd access for code review - Physics Reviewer: contradicts edges, domain-focused loadout for physics validation

AgentConfig dataclass

AgentConfig(
    role: AgentRole,
    name: str,
    description: str,
    model_tier: str = "sonnet",
    tools: list[str] = list(),
    system_prompt_additions: str = "",
    loadout_required: bool = True,
    receives_phase_diffs: bool = False,
    parallel_capable: bool = True,
)

Configuration for an agent role.

SpecialAgentConfig dataclass

SpecialAgentConfig(
    name: str,
    description: str,
    model_tier: str = "sonnet",
    tools: list[str] = list(),
    system_prompt_additions: str = "",
)

Configuration for non-role-based agents (planner, scaffolder, etc.).

resolve_runtime_tools

resolve_runtime_tools(
    logical_tools: list[str],
) -> list[str]

Translate a list of logical tool names into concrete runtime names.

Grep is never introduced. Unknown logical names produce a warning and are skipped. The result is deterministically ordered and deduplicated.

Source code in packages/akms/src/akms/orchestrator/agent_configs.py

def resolve_runtime_tools(logical_tools: list[str]) -> list[str]:
    """Translate a list of logical tool names into concrete runtime names.

    Grep is never introduced. Unknown logical names produce a warning and
    are skipped. The result is deterministically ordered and deduplicated.
    """
    seen: set[str] = set()
    ordered: list[str] = []
    for name in logical_tools or []:
        mapping = TOOL_NAME_MAP.get(name)
        if mapping is None:
            logger.warning("Unknown logical tool name: %r — skipping", name)
            continue
        for concrete in mapping:
            if concrete == "Grep":
                # Defensive — FR-C05 forbids Grep.
                continue
            if concrete not in seen:
                seen.add(concrete)
                ordered.append(concrete)
    return ordered

get_agent_config

get_agent_config(role: AgentRole | str) -> AgentConfig

Get the agent configuration for a role.

Parameters:

Name	Type	Description	Default
role	AgentRole | str	Agent role (enum or string).	required

Returns:

Type	Description
AgentConfig	AgentConfig for the role.

Raises:

Type	Description
ValueError	If role is unknown.

Source code in packages/akms/src/akms/orchestrator/agent_configs.py

def get_agent_config(role: AgentRole | str) -> AgentConfig:
    """Get the agent configuration for a role.

    Args:
        role: Agent role (enum or string).

    Returns:
        AgentConfig for the role.

    Raises:
        ValueError: If role is unknown.
    """
    if isinstance(role, str):
        try:
            role = AgentRole(role)
        except ValueError:
            raise ValueError(f"Unknown agent role: {role}")

    if role not in AGENT_CONFIGS:
        raise ValueError(f"No configuration for role: {role}")

    return AGENT_CONFIGS[role]

get_special_agent_config

get_special_agent_config(name: str) -> SpecialAgentConfig

Get a special (non-role-based) agent configuration.

Parameters:

Name	Type	Description	Default
name	str	Agent name (planner, task_decomposer, scaffolder, phase_agent).	required

Returns:

Type	Description
SpecialAgentConfig	SpecialAgentConfig.

Raises:

Type	Description
ValueError	If agent name is unknown.

Source code in packages/akms/src/akms/orchestrator/agent_configs.py

def get_special_agent_config(name: str) -> SpecialAgentConfig:
    """Get a special (non-role-based) agent configuration.

    Args:
        name: Agent name (planner, task_decomposer, scaffolder, phase_agent).

    Returns:
        SpecialAgentConfig.

    Raises:
        ValueError: If agent name is unknown.
    """
    if name not in SPECIAL_AGENTS:
        raise ValueError(
            f"Unknown special agent: {name}. Available: {list(SPECIAL_AGENTS.keys())}"
        )
    return SPECIAL_AGENTS[name]