feat: improved agent coordination and removal of '3 phases' guidance #129

aaronsteers · 2025-10-10T19:38:37Z

Method: full-text search for 'phase' and replace with new instructions everywhere.

Summary by CodeRabbit

Refactor
- Reworked workflow from a rigid phase-based flow to a stepwise, narrated task approach and unified narration guidance across prompts.
- Updated wording to reference tasks/jobs rather than phases.
Documentation
- Removed Phase 1–3 guidance documents (initial stream read, pagination, remaining streams).
- Removed the phase-based templates used to describe phase details.
Chores
- Minor wording updates across build tooling and run guidance.

github-actions · 2025-10-10T19:38:47Z

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

Testing This Branch via MCP

To test the changes in this specific branch with an MCP client like Claude Desktop, use the following configuration:

{
  "mcpServers": {
    "connector-builder-mcp-dev": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/airbytehq/connector-builder-mcp.git@aj/fix/better-agent-coordination", "connector-builder-mcp"]
    }
  }
}

Testing This Branch via CLI

You can test this version of the MCP Server using the following CLI snippet:

# Run the CLI from this branch:
uvx 'git+https://github.com/airbytehq/connector-builder-mcp.git@aj/fix/better-agent-coordination#egg=airbyte-connector-builder-mcp' --help

PR Slash Commands

Airbyte Maintainers can execute the following slash commands on your PR:

/autofix - Fixes most formatting and linting issues
/poe <command> - Runs any poe command in the uv virtual environment
/poe build-connector prompt="Star Wars API" - Run the connector builder using the Star Wars API.

📝 Edit this welcome message.

coderabbitai · 2025-10-10T19:39:05Z

📝 Walkthrough

Walkthrough

This PR removes three phase-guidance markdown files and deletes Pydantic phase data models. It replaces explicit phase-oriented prompts with a stepwise narrated task approach via INTERNAL_MONOLOGUE_GUIDANCE and updates several docstrings to use job/task wording. No runtime control-flow or algorithmic behavior changes.

Changes

Cohort / File(s)	Summary
Docs: Remove phase guidance `connector_builder_agents/prompts/phase-1-stream-read.md`, `connector_builder_agents/prompts/phase-2-pagination.md`, `connector_builder_agents/prompts/phase-3-remaining-streams.md`	Deleted Phase 1–3 markdown guidance files.
Prompt composition: Stepwise narration `connector_builder_agents/src/guidance.py`	Replaced explicit phase workflow with stepwise narrated task approach; added `INTERNAL_MONOLOGUE_GUIDANCE` and injected it into manager & developer prompt assembly; adjusted wording for progress and exit criteria.
Agents: Docstring wording `connector_builder_agents/src/agents.py`	Updated public function docstrings to remove phase-centric language; no signature or behavior changes.
Phases data models: Removal `connector_builder_agents/src/phases.py`	Removed exported Pydantic models `Phase1Data`, `Phase2Data`, `Phase3Data` and related module content.
Runner: Docstring wording `connector_builder_agents/src/run.py`	Updated `run_manager_developer_build` docstring to drop “3-phase” reference; no logic changes.
Tools: Docstring wording `connector_builder_agents/src/tools.py`	Updated tool docstrings from “phase” to “job”; no logic changes.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant U as User
  participant M as Manager Agent
  participant D as Developer Agent
  participant T as Tools (mark_job_success/failed)
  note over M,D: INTERNAL_MONOLOGUE_GUIDANCE included in both prompts

  U->>M: Start connector build request
  M->>M: Break work into small steps and narrate plan
  loop For each step
    M->>D: Assign next task with context + narration cues
    D->>D: Execute step and narrate progress
    alt Success
      D->>T: mark_job_success
      T-->>D: Ack
      D-->>M: Step results
    else Failure/blocked
      D->>T: mark_job_failed
      T-->>D: Ack
      D-->>M: Error/needs info
    end
    M->>M: Decide next step or finish
  end
  M-->>U: Build outcome and artifacts

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

feat: add internal monologue and smaller steps #113 — Also introduces and injects INTERNAL_MONOLOGUE_GUIDANCE into manager/developer prompts; closely related changes to guidance composition.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly captures the two primary changes in the pull request—enhancing agent coordination and removing references to the three-phase workflow—and aligns directly with the modifications made throughout the codebase and documentation. It is concise, specific, and avoids superfluous details or vague language.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch aj/fix/better-agent-coordination

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f6d5149 and d81baf7.

📒 Files selected for processing (1)

connector_builder_agents/src/run.py (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

connector_builder_agents/src/run.py

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Copilot

Pull Request Overview

This PR refactors the connector building system by removing the rigid "3 phases" approach and replacing it with a more flexible task-based workflow. The change aims to improve agent coordination by allowing for more adaptive and incremental development steps.

Removed the entire phases.py module containing Phase1Data, Phase2Data, and Phase3Data models
Updated documentation and prompts to use "job" and "task" terminology instead of "phase"
Replaced structured phase guidance with flexible step-by-step instructions

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
connector_builder_agents/src/tools.py	Updated function docstrings to reference "job" instead of "phase"
connector_builder_agents/src/run.py	Removed "3-phase" reference from function docstring
connector_builder_agents/src/phases.py	Completely removed file containing phase data models
connector_builder_agents/src/guidance.py	Replaced phase-based workflow with flexible task-based instructions
connector_builder_agents/src/agents.py	Updated agent descriptions to remove phase references
connector_builder_agents/prompts/phase-3-remaining-streams.md	Removed phase-specific prompt file
connector_builder_agents/prompts/phase-2-pagination.md	Removed phase-specific prompt file
connector_builder_agents/prompts/phase-1-stream-read.md	Removed phase-specific prompt file

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

github-actions · 2025-10-10T19:40:28Z

PyTest Results (Fast)

0 tests ±0 0 ✅ ±0 0s ⏱️ ±0s
0 suites ±0 0 💤 ±0
0 files ±0 0 ❌ ±0

Results for commit d81baf7. ± Comparison against base commit 45b1b8c.

♻️ This comment has been updated with latest results.

aaronsteers · 2025-10-12T05:03:07Z

/build-connector

🛠️ Building connector...

Link to job logs.

🟦 Poe command evals run --connector source-jsonplaceholder completed successfully.

✳️ Show/Hide Summary Output

Evaluation Run Summary

Experiment: RXhwZXJpbWVudDo1Mw==

Run Date: 2025-10-12 05:04 UTC

Configuration	Value
developer_model	gpt-5
manager_model	gpt-5
readiness_eval_model	gpt-4o

Experiment Stats

Evaluator	Mean	Min	Max
readiness_eval	❌ 0.00	❌ 0.00	❌ 0.00
streams_eval	✅ 1.00	✅ 1.00	✅ 1.00
Overall	🟡 0.50

Score Level	Count	Percentage
🟡 Partial (0.5-0.74)	1	100%

Per-Connector Results

Comparing to prior experiment: RXhwZXJpbWVudDo0OA==

Connector	Duration	readiness_eval	streams_eval	Overall
source-jsonplaceholder	5m 10s	❌ 0.00 (→)	✅ 1.00 (→)	🟡 0.50 (→)

aaronsteers added 2 commits October 10, 2025 11:56

fix: add internal monologue guidance for manager

578c8d2

feat: remove "3 phases" guidance

488ead4

aaronsteers changed the title ~~Aj/fix/better agent coordination~~ feat: improved agent coordination and removal of '3 phases' guidance Oct 10, 2025

aaronsteers requested review from Copilot and pedroslopez October 10, 2025 19:39

Copilot AI reviewed Oct 10, 2025

View reviewed changes

Merge branch 'main' into aj/fix/better-agent-coordination

4258bb9

github-actions bot added the enhancement New feature or request label Oct 10, 2025

aaronsteers mentioned this pull request Oct 10, 2025

fix: Add validation for manifest streams structure to prevent AttributeError #130

Merged

4 tasks

aaronsteers added 3 commits October 10, 2025 14:03

Merge branch 'main' into aj/fix/better-agent-coordination

a97abd4

Merge branch 'main' into aj/fix/better-agent-coordination

f6d5149

Merge branch 'main' into aj/fix/better-agent-coordination

d81baf7

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: improved agent coordination and removal of '3 phases' guidance #129

feat: improved agent coordination and removal of '3 phases' guidance #129

Uh oh!

aaronsteers commented Oct 10, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

github-actions bot commented Oct 10, 2025

Uh oh!

coderabbitai bot commented Oct 10, 2025 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions bot commented Oct 10, 2025 •

edited

Loading

Uh oh!

aaronsteers commented Oct 12, 2025 •

edited by github-actions bot

Loading

Evaluation Run Summary

Experiment Stats

Per-Connector Results

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

feat: improved agent coordination and removal of '3 phases' guidance #129

Are you sure you want to change the base?

feat: improved agent coordination and removal of '3 phases' guidance #129

Uh oh!

Conversation

aaronsteers commented Oct 10, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

github-actions bot commented Oct 10, 2025

👋 Greetings, Airbyte Team Member!

Testing This Branch via MCP

Testing This Branch via CLI

PR Slash Commands

Uh oh!

coderabbitai bot commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Pre-merge checks and finishing touches

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

github-actions bot commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PyTest Results (Fast)

Uh oh!

aaronsteers commented Oct 12, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Evaluation Run Summary

Experiment Stats

Per-Connector Results

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

aaronsteers commented Oct 10, 2025 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Oct 10, 2025 •

edited

Loading

github-actions bot commented Oct 10, 2025 •

edited

Loading

aaronsteers commented Oct 12, 2025 •

edited by github-actions bot

Loading