From 578c8d2eb3675e4d4ff71a055bccd0d215edbb44 Mon Sep 17 00:00:00 2001 From: "Aaron (AJ) Steers" Date: Fri, 10 Oct 2025 11:56:33 -0700 Subject: [PATCH 1/2] fix: add internal monologue guidance for manager --- connector_builder_agents/src/guidance.py | 1 + 1 file changed, 1 insertion(+) diff --git a/connector_builder_agents/src/guidance.py b/connector_builder_agents/src/guidance.py index cf94144..561c0fd 100644 --- a/connector_builder_agents/src/guidance.py +++ b/connector_builder_agents/src/guidance.py @@ -69,6 +69,7 @@ def get_default_manager_prompt( api_name=api_name, instructions=instructions, ), + INTERNAL_MONOLOGUE_GUIDANCE, get_project_directory_prompt(project_directory), RECOMMENDED_PROMPT_PREFIX, ROOT_PROMPT_FILE_STR, From 488ead4b6ef120f2a5dd81c052d8df5982875505 Mon Sep 17 00:00:00 2001 From: "Aaron (AJ) Steers" Date: Fri, 10 Oct 2025 12:14:19 -0700 Subject: [PATCH 2/2] feat: remove "3 phases" guidance --- .../prompts/phase-1-stream-read.md | 35 ------------- .../prompts/phase-2-pagination.md | 33 ------------ .../prompts/phase-3-remaining-streams.md | 34 ------------- connector_builder_agents/src/agents.py | 4 +- connector_builder_agents/src/guidance.py | 30 +++++------ connector_builder_agents/src/phases.py | 50 ------------------- connector_builder_agents/src/run.py | 2 +- connector_builder_agents/src/tools.py | 6 +-- 8 files changed, 22 insertions(+), 172 deletions(-) delete mode 100644 connector_builder_agents/prompts/phase-1-stream-read.md delete mode 100644 connector_builder_agents/prompts/phase-2-pagination.md delete mode 100644 connector_builder_agents/prompts/phase-3-remaining-streams.md delete mode 100644 connector_builder_agents/src/phases.py diff --git a/connector_builder_agents/prompts/phase-1-stream-read.md b/connector_builder_agents/prompts/phase-1-stream-read.md deleted file mode 100644 index ef3f876..0000000 --- a/connector_builder_agents/prompts/phase-1-stream-read.md +++ /dev/null @@ -1,35 +0,0 @@ -# Phase 1: First Successful Stream Read - -You are working on Phase 1 of connector development. Your goal is to establish basic connectivity and successfully read records from one stream. - -## Objectives -- Research the target API and understand its structure -- Create initial manifest using the scaffold tool -- Set up proper authentication (request secrets from user if needed) -- Configure one stream without pagination initially -- Validate that you can read records from this stream - -## Key MCP Tools for This Phase -- `create_connector_manifest_scaffold` - Generate initial manifest structure -- `populate_dotenv_missing_secrets_stubs` - Set up authentication secrets -- `execute_stream_test_read` - Test reading from the stream -- `validate_manifest` - Ensure manifest structure is correct - -## Success Criteria -- Authentication is working correctly -- Can read at least a few records from one stream -- No pagination configured yet (that's Phase 2) -- Manifest validates successfully - -## Process -1. Research the API documentation online -2. Create initial manifest scaffold -3. Set up authentication (ask user for secrets if needed) -4. Configure one stream without pagination -5. Test reading records from the stream -6. Update checklist.md with progress - -## Next Phase -Once you can successfully read records from one stream, the manager will delegate Phase 2 to add pagination support. - -Remember to update your checklist.md file as you complete each step. diff --git a/connector_builder_agents/prompts/phase-2-pagination.md b/connector_builder_agents/prompts/phase-2-pagination.md deleted file mode 100644 index e976079..0000000 --- a/connector_builder_agents/prompts/phase-2-pagination.md +++ /dev/null @@ -1,33 +0,0 @@ -# Phase 2: Working Pagination - -You are working on Phase 2 of connector development. Your goal is to implement and validate pagination for the working stream from Phase 1. - -## Objectives -- Add pagination configuration to the manifest -- Test reading multiple pages of data -- Confirm you can reach the end of the stream -- Verify record counts are not suspicious multiples -- Update checklist.md with progress - -## Key MCP Tools for This Phase -- `execute_stream_test_read` - Test reading with pagination -- `validate_manifest` - Ensure manifest structure is correct -- `get_connector_builder_docs` - Get pagination documentation if needed - -## Success Criteria -- Pagination works correctly and can read multiple pages -- Can reach the end of the stream without errors -- Record counts are not suspicious multiples (10, 25, page size, etc.) -- Stream test completes successfully with high record count - -## Process -1. Add pagination configuration to the existing manifest -2. Test reading a few pages of data -3. Test reading to the end of the stream with high record limit -4. Verify record counts are realistic (not suspicious multiples) -5. Update checklist.md with progress - -## Next Phase -Once pagination is working correctly, the manager will delegate Phase 3 to add all remaining streams. - -Remember to disable records and raw responses when testing high record counts to avoid overloading the context window. diff --git a/connector_builder_agents/prompts/phase-3-remaining-streams.md b/connector_builder_agents/prompts/phase-3-remaining-streams.md deleted file mode 100644 index 346d37e..0000000 --- a/connector_builder_agents/prompts/phase-3-remaining-streams.md +++ /dev/null @@ -1,34 +0,0 @@ -# Phase 3: Add Remaining Streams - -You are working on Phase 3 of connector development. Your goal is to add and validate all remaining streams for the connector. - -## Objectives -- Identify all available streams from API documentation -- Add each stream to the manifest one by one -- Test each stream individually -- Run full connector readiness test -- Update checklist.md with final results - -## Key MCP Tools for This Phase -- `execute_stream_test_read` - Test each new stream individually -- `run_connector_readiness_test_report` - Run comprehensive connector test -- `validate_manifest` - Ensure manifest structure is correct - -## Success Criteria -- All available streams are added to the manifest -- Each stream can be read successfully -- Full connector readiness test passes -- No warnings or errors in the final test report - -## Process -1. Research API documentation to identify all available streams -2. Add each stream to the manifest one by one -3. Test each new stream individually before proceeding -4. Run full connector readiness test on all streams -5. Address any warnings or errors -6. Update checklist.md with final results and stream counts - -## Completion -This is the final phase. Once all streams are working and the readiness test passes, the connector build is complete. - -Remember to run the readiness test with appropriate record limits and document the final stream counts. diff --git a/connector_builder_agents/src/agents.py b/connector_builder_agents/src/agents.py index ba49998..35a732b 100644 --- a/connector_builder_agents/src/agents.py +++ b/connector_builder_agents/src/agents.py @@ -34,7 +34,7 @@ def create_developer_agent( session_state: SessionState, mcp_servers: list, ) -> OpenAIAgent: - """Create the developer agent that executes specific phases.""" + """Create the developer agent that will work on the connector build tasks.""" return OpenAIAgent( name="MCP Connector Developer", instructions=get_default_developer_prompt( @@ -61,7 +61,7 @@ def create_manager_agent( session_state: SessionState, mcp_servers: list, ) -> OpenAIAgent: - """Create the manager agent that orchestrates the 3-phase workflow.""" + """Create the manager agent that orchestrates connector builds.""" return OpenAIAgent( name="Connector Builder Manager", instructions=get_default_manager_prompt( diff --git a/connector_builder_agents/src/guidance.py b/connector_builder_agents/src/guidance.py index 561c0fd..67231b9 100644 --- a/connector_builder_agents/src/guidance.py +++ b/connector_builder_agents/src/guidance.py @@ -27,28 +27,30 @@ Instructions: {instructions} -Execute the phases in order: -1. Use start_phase_1_stream_read to delegate Phase 1 (first successful stream read) -2. After Phase 1 completes, use start_phase_2_pagination to delegate Phase 2 (working pagination) -3. After Phase 2 completes, use start_phase_3_remaining_streams to delegate Phase 3 (add remaining streams) +Execute tasks in small steps, narrating your internal monologue as you go. In general, +you can break the work into small incremental steps: +1. Aim for a first successful stream read, ignoring pagination and additional streams. +2. Once you have a successful read, see if you can add pagination support to that stream. +3. Once you are able to read all records from that stream, try to add more streams incrementally, +focusing on adding and then testing one new stream at a time. -Monitor progress and ensure each phase completes successfully before moving to the next. +Monitor progress and ensure each step completes successfully before moving to the next. When checking on the progress of your developer: -- Use the `get_progress_log_text` tool to get the latest progress log. -- Use the `get_latest_readiness_report` tool to get the latest readiness report. +- Use your tools to retrieve the latest progress log and the "readiness report". +- Based on the progress log and readiness report, determine what next steps are needed. If the build is complete, summarize the results and evaluate whether they meet the requirements. If -not, you can repeat a phase, calling out what they missed and suggesting next steps. Determine the -next phase or next appropriate action based on their progress. +not, you can repeat a task, calling out what they missed and suggesting next steps. Determine the +next steps or next appropriate action based on their progress. ## Exit Criteria -- You are done when all phases are complete and the connector is ready for review. When this is the - case, call the `mark_job_success` tool. (Only call if you are sure the build is fully complete - and fully tested.) -- If you become fully blocked and cannot proceed, call the - `mark_job_failed` tool, providing a summary of the issues encountered. (Last resort only.) +- You are done when all deliverables are complete, all streams have been added, and the connector + is fully tested and working properly. When this is the case, call the `mark_job_success` tool. + (Only call if you are sure the build is fully complete and fully tested.) +- If you become fully blocked and cannot proceed, use your provided tool to mark the task as failed, + providing a summary of the issues encountered. (Last resort only.) """ diff --git a/connector_builder_agents/src/phases.py b/connector_builder_agents/src/phases.py deleted file mode 100644 index 0025b84..0000000 --- a/connector_builder_agents/src/phases.py +++ /dev/null @@ -1,50 +0,0 @@ -# Copyright (c) 2025 Airbyte, Inc., all rights reserved. -"""Data models for different phases of connector development.""" - -from pydantic import BaseModel - - -class Phase1Data(BaseModel): - """Data for Phase 1: First successful stream read.""" - - api_name: str - additional_instructions: str = "" - phase_description: str = "Phase 1: First Successful Stream Read" - objectives: list[str] = [ - "Research the target API and understand its structure. ", - "Create initial manifest using the scaffold tool. ", - "Set up proper authentication (request secrets from user if needed). ", - "Configure one stream without pagination initially. ", - "Validate that you can read records from this stream. ", - "You are done (report back) as soon as you have a successful read and the above objectives are met. ", - ] - - -class Phase2Data(BaseModel): - """Data for Phase 2: Working pagination.""" - - api_name: str - phase_description: str = "Phase 2: Working Pagination" - objectives: list[str] = [ - "Add pagination configuration to the manifest", - "Test reading multiple pages of data", - "Confirm you can reach the end of the stream", - "Verify record counts are not suspicious multiples", - "Update checklist.md with progress", - "You are done (report back) as soon as you have confirmed pagination is working and the above objectives are met. ", - ] - - -class Phase3Data(BaseModel): - """Data for Phase 3: Add remaining streams.""" - - api_name: str - phase_description: str = "Phase 3: Add Remaining Streams" - objectives: list[str] = [ - "Identify all available streams from API documentation. ", - "Add each stream to the manifest one by one. ", - "Test each stream individually. ", - "Run full connector readiness test. ", - "Update checklist.md with final results. ", - "You are done (report back) once all streams are confirmed to be working and all above objectives are met. ", - ] diff --git a/connector_builder_agents/src/run.py b/connector_builder_agents/src/run.py index de315a4..0bb508e 100644 --- a/connector_builder_agents/src/run.py +++ b/connector_builder_agents/src/run.py @@ -200,7 +200,7 @@ async def run_manager_developer_build( manager_model: str = DEFAULT_MANAGER_MODEL, session_id: str | None = None, ) -> list[RunResult]: - """Run a 3-phase connector build using manager-developer architecture.""" + """Run connector build using manager-developer architecture.""" # Generate session_id if not provided if session_id is None: session_id = generate_session_id() diff --git a/connector_builder_agents/src/tools.py b/connector_builder_agents/src/tools.py index 6c65ea0..4b11586 100644 --- a/connector_builder_agents/src/tools.py +++ b/connector_builder_agents/src/tools.py @@ -216,9 +216,9 @@ def create_mark_job_success_tool(session_state: SessionState): @function_tool def mark_job_success() -> None: - """Mark the current phase as complete. + """Mark the current job as complete. - This should be called when all objectives for the current phase are met, and only after + This should be called when all objectives for the current job are met, and only after a successful connector readiness report has been saved to the workspace directory. """ session_state.is_success = True @@ -232,7 +232,7 @@ def create_mark_job_failed_tool(session_state: SessionState): @function_tool def mark_job_failed() -> None: - """Mark the current phase as failed. + """Mark the job as failed. This should only be called in the event that it is no longer possible to make progress. Before calling this tool, you should attempt to save the latest output of the