feat: Add agent identity debug logging to expose coordination issues

[aaronsteers]

feat: Add agent identity debug logging to expose coordination issues

Summary

Adds explicit agent identity logging at key coordination points in the manager-developer orchestration system. This diagnostic change helps identify agent identity confusion issues where agents lose track of their role during handoffs and iterations.

Changes:

• Enhanced handoff logging in agents.py with directional indicators [MANAGER → DEVELOPER] and [DEVELOPER → MANAGER]
• Added iteration counter and start/completion logging in the orchestration loop in run.py
• Each loop iteration now logs which agent is starting and which agent completed the work

This addresses debugging needs identified in investigation of PR #122 execution logs where developer agents exhibited manager-like behavior (attempting to delegate tasks).

Review & Testing Checklist for Human

• Test multi-agent workflow end-to-end - Run a connector build and verify the new logging appears correctly and helps distinguish agent roles
• Verify log clarity - Confirm the new log messages are helpful for debugging without creating excessive noise in the output
• Test iteration counting - Ensure iteration counter increments correctly across multiple loop iterations and doesn't reset unexpectedly

Notes

These changes are diagnostic only - they expose coordination issues but don't fix the underlying root causes (commented-out previous_response_id and completion signaling issues). Those fixes are being addressed in separate PRs.

Requested by: @aaronsteers
Session: https://app.devin.ai/sessions/6acb99e3b34a4918af907764ca9b55c3

Summary by CodeRabbit

• New Features
  • Added per-iteration progress tracking, showing iteration numbers and the active agent for clearer build progression.
  • Introduced distinct iteration completion and final output lines each cycle to make outcomes easier to scan.
  • Enhanced agent handoff logs with explicit manager ↔ developer labels, improving readability and traceability during collaboration.
• Style
  • Updated log message wording for consistency and clarity without changing behavior or interfaces.

[devin-ai-integration]

Original prompt from AJ Steers

@Devin - Review this execution log: <https://github.com/airbytehq/connector-builder-mcp/actions/runs/18415068059/job/52476733729?pr=122>

You'll note the "NOW:" "OBSERVED:", "NEXT:" pattern is not being practiced until the work is basically done. This tells me the prompt is not properly routing to the developer instructions in the first step. I also note from that log that the agent is already done but the agent is not aware so it tries to work again on the problem. See if you can find the problem with routing and/or prompting and/or coordination between manager and developer agents.
Thread URL: https://airbytehq-team.slack.com/archives/D089P0UPVT4/p1760121663439179?thread_ts=1760121663.439179

[devin-ai-integration]

🤖 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

[coderabbitai]

📝 Walkthrough

Walkthrough

Updates user-facing log messages in agent delegation/handback callbacks and adds iteration_count with per-iteration logging in the manager-developer run loop. Final output logging is split into iteration completion and agent output lines. No public interfaces or control flow are changed.

Changes

Cohort / File(s)	Summary of Changes
Agent delegation/handback logging connector_builder_agents/src/agents.py	Replaces log text in on_developer_delegation and on_manager_handback callbacks; no signature or control-flow changes.
Run loop iteration logging connector_builder_agents/src/run.py	Adds iteration_count, logs iteration progress at loop start, and splits per-iteration end logs into completion line and agent output line; no API changes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• feat: add internal monologue and smaller steps #113 — Modifies the same agent delegation and manager handback callbacks in agents.py, overlapping with this PR’s logging changes.

Suggested labels

enhancement

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title clearly and succinctly summarizes the main change of adding diagnostic debug logs to surface agent identity and coordination issues, reflecting both the enhanced handoff messages in agents.py and iteration logging in run.py without extraneous detail.

✨ 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 devin/1760131322-add-agent-identity-logging

---

📜 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 374cb49 and 8adbd92.

📒 Files selected for processing (2)

• connector_builder_agents/src/agents.py (2 hunks)
• connector_builder_agents/src/run.py (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

connector_builder_agents/src/run.py (1)

connector_builder_agents/src/tools.py (3)

• is_complete (53-55)
• is_complete (179-181)
• update_progress_log (191-215)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Run Evals (Single Connector)
• GitHub Check: Pytest (Fast)

🔇 Additional comments (5)

connector_builder_agents/src/agents.py (2)

118-122: LGTM! Directional indicator improves diagnostic clarity.

The addition of [MANAGER → DEVELOPER] makes the handoff direction explicit, which directly supports the PR's goal of surfacing agent coordination behavior.

---

132-139: LGTM! Explicit handback direction aids debugging.

The [DEVELOPER → MANAGER] prefix clearly identifies the return path, helping diagnose cases where agents may lose track of their roles during handoffs.

connector_builder_agents/src/run.py (3)

262-268: LGTM! Iteration tracking and start logging enhance visibility.

The iteration counter correctly starts at 0 and increments to 1 for the first iteration. The start log consistently shows manager_agent.name because the manager orchestrates each iteration, which aligns with the manager-developer architecture.

This will help identify coordination issues by showing which agent starts versus which agent completes each iteration.

---

278-281: LGTM! Two-part completion logging provides clear iteration closure.

The split into separate log entries—one for iteration metadata (Iteration N completed. Last agent: X) and one for agent output (🤖 {name}: {output})—improves log readability and makes it easier to track which agent completed the work.

---

260-260: Note: Commented-out previous_response_id logic to be addressed separately.

The commented-out code related to previous_response_id handling is acknowledged in the PR description as a known issue that will be fixed in a separate PR. This is appropriate for a diagnostic-focused change.

Verify that the follow-up PR to restore proper previous_response_id handling is tracked, as this logic is important for maintaining conversation context across iterations.

Also applies to: 274-274, 277-277

---

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

[github-actions]

👋 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/1760131322-add-agent-identity-logging", "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/1760131322-add-agent-identity-logging#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]

PyTest Results (Fast)

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

Results for commit 80b5a1e. ± Comparison against base commit f45ab1a.

♻️ This comment has been updated with latest results.