feat: add manager-developer agent architecture with handoffs #64

aaronsteers · 2025-09-08T20:42:25Z

feat: add manager-developer agent architecture with handoffs

Summary

This PR introduces a new two-agent architecture for the Builder MCP system where a "manager" agent orchestrates the connector building process by delegating work to a "developer" agent across 3 phases using the openai-agents library's handoffs mechanism.

Key Components:

Manager Agent: Orchestrates the overall workflow and delegates specific phases
Developer Agent: Executes technical implementation of each phase using MCP tools
Phase Data Models: Pydantic models for type-safe communication between agents
Phase Prompts: Detailed guidance templates for each development phase

Workflow Phases:

Phase 1: First successful stream read (authentication + basic connectivity)
Phase 2: Working pagination (add and validate pagination)
Phase 3: Add remaining streams (complete connector with all streams)

The new architecture maintains full compatibility with existing MCP tools and infrastructure while providing more structured, delegated connector development.

Review & Testing Checklist for Human

End-to-end workflow test: Run poe run-manager-developer "Test API" and verify the manager agent successfully delegates to developer agent across all 3 phases
Handoffs verification: Confirm that agent handoffs work correctly and phase data is passed properly between manager and developer agents
Existing functionality: Test that poe run-mcp-agent still works to ensure no regressions in single-agent architecture

Notes

The implementation uses the same MCP servers and tools as the existing single-agent system
New poe tasks added for convenience: run-manager-developer, run-manager-developer-custom, run-manager-developer-headless
Phase-specific prompt templates in prompts/ directory provide detailed guidance for developer agent
Session: Requested by @aaronsteers - https://app.devin.ai/sessions/211423f9397f444eae609df865e79dd0

Important

Auto-merge enabled.

This PR is set to merge automatically when all requirements are met.

- Create two-agent system where manager orchestrates and developer executes - Implement 3-phase workflow: stream read, pagination, remaining streams - Use openai-agents handoffs for structured agent communication - Add Pydantic models for type-safe data passing between agents - Create phase-specific prompt templates for developer guidance - Update README and poe tasks for new architecture - Maintain compatibility with existing MCP tools and infrastructure Co-Authored-By: AJ Steers <[email protected]>

devin-ai-integration · 2025-09-08T20:42:30Z

Original prompt from AJ Steers

@Devin - Can you take a look at the new Builder MCP agent code in examples directory? I'd like to introduce a second "manager" agent, and designate the current agent as "developer". The manager agent, should delegate the connector build as 3 parts: (1) first successful stream read, (2) working pagination, (3) added remaining streams.
Thread URL: https://airbytehq-team.slack.com/archives/D089P0UPVT4/p1757362864848319?thread_ts=1757362864.848319

devin-ai-integration · 2025-09-08T20:42:31Z

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

Disable automatic comment and CI monitoring

github-actions · 2025-09-08T20:42:41Z

👋 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@devin/1757363034-manager-developer-agents", "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@devin/1757363034-manager-developer-agents#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.

github-actions · 2025-09-08T20:44:20Z

PyTest Results (Fast)

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

Results for commit efd86b3. ± Comparison against base commit 3d1e4c9.

♻️ This comment has been updated with latest results.

Co-Authored-By: AJ Steers <[email protected]>

aaronsteers · 2025-09-08T20:53:20Z

examples/phase_models.py

Delete this file and move it's content into the python file and/or into frontmatter of the prompt md files

- Move Pydantic models from separate phase_models.py into run_manager_developer_agents.py - Delete phase_models.py file as requested in GitHub comment - Update imports to use pydantic.BaseModel directly - Maintain unified script interface with no separate code paths - All functionality preserved including handoffs mechanism Co-Authored-By: AJ Steers <[email protected]>

- Merge run_manager_developer_agents.py functionality into run_mcp_agent.py - Use headless mode to automatically trigger manager-developer architecture - Use interactive mode for single-agent with conversation loop - Delete separate run_manager_developer_agents.py to eliminate code paths - Update poe tasks to use unified script interface - Preserve all existing CLI arguments and handoffs mechanism - Update documentation to reflect unified interface Co-Authored-By: AJ Steers <[email protected]>

…ger-developer-agents

github-actions · 2025-09-18T15:28:54Z

PyTest Results (Full)

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

Results for commit efd86b3.

♻️ This comment has been updated with latest results.

devin-ai-integration bot assigned aaronsteers Sep 8, 2025

github-actions bot added the enhancement New feature or request label Sep 8, 2025

fix: apply ruff formatting to phase_models.py

8a8d5a6

Co-Authored-By: AJ Steers <[email protected]>

aaronsteers commented Sep 8, 2025

View reviewed changes

devin-ai-integration bot and others added 10 commits September 8, 2025 20:55

clean up

b1064f3

clean up

e64680b

Merge remote-tracking branch 'origin/main' into devin/1757363034-mana…

9ab80e1

…ger-developer-agents

fix var

bc06f02

working manger-developer multi-agent flow 🎉

8f5d98a

rename: run-connector-build >> build-connector

c86c9b6

update github workflows

2056c8f

Merge branch 'main' into devin/1757363034-manager-developer-agents

2cfe521

aaronsteers marked this pull request as draft September 18, 2025 15:26

aaronsteers marked this pull request as ready for review September 18, 2025 15:26

autofix

ed72baa

aaronsteers added 4 commits September 18, 2025 08:31

fix 'examples' dir refs

9c0a15a

pre-install poethepoet

fbe4623

add debug info, servers cleanup

0229f32

clean up test workflow

efd86b3

aaronsteers enabled auto-merge (squash) September 18, 2025 15:44

aaronsteers merged commit 6f30ffa into main Sep 18, 2025
17 checks passed

aaronsteers deleted the devin/1757363034-manager-developer-agents branch September 18, 2025 15:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add manager-developer agent architecture with handoffs #64

feat: add manager-developer agent architecture with handoffs #64

Uh oh!

aaronsteers commented Sep 8, 2025 •

edited by github-actions bot

Loading

Uh oh!

devin-ai-integration bot commented Sep 8, 2025

Uh oh!

devin-ai-integration bot commented Sep 8, 2025

Uh oh!

github-actions bot commented Sep 8, 2025

Uh oh!

github-actions bot commented Sep 8, 2025 •

edited

Loading

Uh oh!

aaronsteers Sep 8, 2025

Uh oh!

github-actions bot commented Sep 18, 2025 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

feat: add manager-developer agent architecture with handoffs #64

feat: add manager-developer agent architecture with handoffs #64

Uh oh!

Conversation

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

Uh oh!

feat: add manager-developer agent architecture with handoffs

Summary

Review & Testing Checklist for Human

Notes

Uh oh!

devin-ai-integration bot commented Sep 8, 2025

Uh oh!

devin-ai-integration bot commented Sep 8, 2025

🤖 Devin AI Engineer

Uh oh!

github-actions bot commented Sep 8, 2025

👋 Greetings, Airbyte Team Member!

Testing This Branch via MCP

Testing This Branch via CLI

PR Slash Commands

Uh oh!

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

Uh oh!

PyTest Results (Fast)

Uh oh!

aaronsteers Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

PyTest Results (Full)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

aaronsteers commented Sep 8, 2025 •

edited by github-actions bot

Loading

github-actions bot commented Sep 8, 2025 •

edited

Loading

github-actions bot commented Sep 18, 2025 •

edited

Loading