Building Specialized Agents

From Theory To Tools

In our previous lesson, we discussed the theory of agent orchestration . We learned that using one large AI for a long project often leads to context decay, where the AI starts making mistakes because it is trying to remember too much at once. The solution is to use a Main Agent that delegates work to specialized Subagents . In this lesson, we move from theory to tools. We will learn how to actually build these specialized agents. On CodeSignal, these agents are defined as TOML configuration files stored in a specific folder: .codex/agents/ . Each role is registered in your .codex/config.toml, then its detailed settings live in a separate .toml file. By creating these files, you are giving Codex a set of specialized "employees" it can hire to perform specific tasks with high precision.

The Anatomy Of A Specialist

In Unit 1 you already registered an agent role in .codex/config.toml and configured it with a role-specific TOML file. Every specialized agent follows that same three-part structure: Identity (the registration entry and model settings), Role (the developer_instructions system prompt that defines what the agent does), and Completion Criteria (a Standards section inside those instructions that lists what must be true before the agent reports "done"). We will apply this pattern directly to two new specialists below.

The Task Executor: Our Primary Builder

The Task Executor is your primary worker. Its job is to take a single task from your tasks.md file and turn it into working, tested code. You already saw its basic structure in Unit 1. What makes it effective in practice is the Process section of developer_instructions, which enforces a Test-First workflow—writing the test before the code to ensure we build exactly what is needed: text ## Process 1. **Understand Task** - Read acceptance criteria from the spec. 2. **Test-First Implementation** - Write failing tests. - Verify they fail. - Implement code to make them pass. 3. **Self-Validate** - Run tests and check for type errors. ## Process 1. **Understand Task** - Read acceptance criteria from the spec. 2. **Test-First Implementation** - Write failing tests. - Verify they fail. - Implement code to make them pass. 3. **Self-Validate** - Run tests and check for type errors. After the process, we define the Standards . These are the "laws" the agent must follow, such as requiring 90% code coverage. This ensures that even if you aren't watching, the agent maintains high quality. text ## Standards - Coverage \geq90% - All tests pass - No type errors (using mypy) ## Standards - Coverage \geq90% - All tests pass - No type errors (using mypy) This agent can be summoned by asking Codex to: Spawn a task-executor agent: "Execute T001: Add priority field to Task model" .

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

The Test Enhancer: The Quality Auditor

Sometimes, a developer moves too fast and misses edge cases. That is why we build a Test Enhancer. This agent doesn't write new features; it only looks at existing code and tries to break it with better tests.

We start by registering the role in .codex/config.toml and creating .codex/agents/test-enhancer.toml:

.codex/config.toml:

TOML

[agents.test-enhancer]
description = "Improves test coverage and identifies missing test cases"
config_file = "agents/test-enhancer.toml"

[agents.test-enhancer]
description = "Improves test coverage and identifies missing test cases"
config_file = "agents/test-enhancer.toml"

.codex/agents/test-enhancer.toml:

TOML

model = "gpt-5.3-codex"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"

model = "gpt-5.3-codex"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"

Next, we define its Role and Process inside the developer_instructions. The core of this agent is its ability to check code coverage—a measurement of how much of your code is actually exercised by your tests.

TOML

developer_instructions = """
## Your Role
You are a test quality specialist focused on improving code coverage and identifying edge cases.
## Process
1. **Check Current Coverage**
   Run: pytest --cov=src/module --cov-report=term tests/
2. **Identify Missing Tests**
   - Analyze uncovered lines in the coverage report.
   - Look for error paths or edge cases not covered.
   - Check boundary conditions and input validation.
3. **Implement Tests**
   - Write tests for uncovered code paths.
   - Focus on error handling and edge cases.
4. **Verify Improvement**
   - Re-run coverage check.
   - Confirm all new tests pass.
## Standards
- Coverage ≥95%
- All tests pass
- Edge cases tested (null, empty, invalid inputs)
- Error paths covered
"""

developer_instructions = """
## Your Role
You are a test quality specialist focused on improving code coverage and identifying edge cases.
## Process
1. **Check Current Coverage**
   Run: pytest --cov=src/module --cov-report=term tests/
2. **Identify Missing Tests**
   - Analyze uncovered lines in the coverage report.
   - Look for error paths or edge cases not covered.
   - Check boundary conditions and input validation.
3. **Implement Tests**
   - Write tests for uncovered code paths.
   - Focus on error handling and edge cases.
4. **Verify Improvement**
   - Re-run coverage check.
   - Confirm all new tests pass.
## Standards
- Coverage ≥95%
- All tests pass
- Edge cases tested (null, empty, invalid inputs)
- Error paths covered
"""

In a production environment, you might run the task-executor first to build a feature, then immediately follow up with the test-enhancer to ensure no bugs are hiding in the "uncovered" lines of code. You would summon this agent by asking Codex to: Spawn a test-enhancer agent: "Enhance tests for Task model".

On CodeSignal, the libraries needed for this, like pytest and pytest-cov, are usually pre-installed for you.

From Theory To Tools

The Anatomy Of A Specialist

The Task Executor: Our Primary Builder

Join the 1M+ learners on CodeSignal

The Test Enhancer: The Quality Auditor

Completion Reporting & Orchestration

Summary And Practice Preview