fix(agents-core): update tool relations when renaming sub-agent IDs for mcp/function tools

[dimaMachina]

No description provided.

[changeset-bot]

🦋 Changeset detected

Latest commit: c22c49f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages

Name	Type
@inkeep/agents-core	Patch
@inkeep/agents-api	Patch
@inkeep/agents-manage-ui	Patch
@inkeep/agents-cli	Patch
@inkeep/agents-sdk	Patch
@inkeep/ai-sdk-provider	Patch
@inkeep/create-agents	Patch
@inkeep/agents-manage-mcp	Patch
@inkeep/agents-mcp	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
agents-api	Ready	Preview, Comment	Jan 29, 2026 10:27am
agents-docs	Ready	Preview, Comment	Jan 29, 2026 10:27am
agents-manage-ui	Ready	Preview, Comment	Jan 29, 2026 10:27am

[claude]

Claude finished @dimaMachina's task —— View job

---

PR Review: Tool Relations Update for Sub-Agent ID Renaming

I've conducted a comprehensive review of this PR that addresses a critical issue where tool relations weren't properly maintained when sub-agent IDs were renamed.

Executive Summary

This is a well-implemented bug fix that addresses a data consistency issue in the agent management system. The implementation correctly handles both MCP and function tool relation updates, includes comprehensive test coverage, and follows established patterns.

---

✅ Strengths

1. Solid Problem Definition & Solution

• Addresses a real data integrity issue where tool relations would become orphaned when sub-agent IDs change
• Uses existing relationId parameter to ensure specific relations are updated rather than creating duplicates
• Handles both MCP tools and function tools consistently

2. Excellent Test Coverage

// packages/agents-core/src/__tests__/integration/data-access/agentFull.rename-sub-agent-id.test.ts
- Sets up realistic scenario with both MCP and function tool relations
- Verifies that relations are properly relinked to new sub-agent ID
- Confirms old sub-agent is deleted and new one is created
- Uses proper database assertions with relation IDs

3. Architectural Consistency

• Leverages existing upsertSubAgentToolRelation and upsertSubAgentFunctionToolRelation functions
• Follows established error handling patterns with detailed logging
• Integrates seamlessly into existing updateFullAgentServerSide workflow

4. Defensive Programming

// Only processes relations that have agentToolRelationId
if (!canUseItem.agentToolRelationId) {
  continue;
}

This prevents unnecessary operations and ensures only intended relations are updated.

---

⚠️ Areas for Consideration

1. Performance Impact
The new code adds another Promise.all loop that processes tool relations. While the implementation is correct, consider:

// Current: Sequential processing after sub-agents are created
await Promise.all(subAgentPromises);
// Then: Tool relation relinking
await Promise.all(relinkToolRelationPromises);

Suggestion: Monitor performance impact in production, especially for agents with many tool relations.

2. Race Condition Potential
The relinking happens after sub-agent creation but before the main tool relation processing:

// 1. Sub-agents created/updated
// 2. Tool relations relinked (NEW)  
// 3. Original tool relation processing continues

Risk: If the original tool processing logic also handles updates, there could be competing updates to the same relations.

3. Incomplete Error Context

logger.error({
  subAgentId,
  relationId: canUseItem.agentToolRelationId,
  toolId: canUseItem.toolId,
  error,
}, 'Failed to relink tool relation during sub-agent update');

Suggestion: Include agentId and projectId in error logging for better debugging context.

4. Missing Edge Case Handling

• What happens if the tool or function tool referenced by the relation no longer exists?
• Should there be validation that the relationId actually exists before attempting to update?

---

🔧 Technical Implementation Review

Database Operations ✅

• Correctly uses existing upsert functions that handle the update-by-relationId pattern
• Proper error handling with detailed logging
• Transaction safety maintained through existing patterns

Code Organization ✅

• Logical placement within the update flow
• Clear variable naming and structure
• Appropriate use of async/await with Promise.all

Testing ✅

• Integration test covers the critical path
• Tests both MCP and function tool scenarios
• Proper database setup and teardown
• Realistic test data and assertions

---

🚨 Critical Questions

1. Idempotency: Is this operation idempotent? What happens if updateFullAgentServerSide is called multiple times with the same data?

2. Partial Failures: If some tool relations fail to relink but others succeed, what's the system state? Should this be wrapped in a transaction?

3. Backward Compatibility: Are there any client-side components that cache sub-agent IDs and might break when IDs change?

---

🎯 Recommendations

Immediate (Low Risk)

• Add agentId and projectId to error logging context
• Consider adding a debug log when relinkToolRelationPromises.length > 0 to track when this code path executes

Future Considerations (Medium Priority)

• Monitor performance metrics for agents with many tool relations
• Consider adding relation existence validation before updates
• Evaluate if this logic should be wrapped in a database transaction for atomicity

Architecture (Long-term)

• Document this behavior in the agent update workflow documentation
• Consider if tool relation management should be extracted into a dedicated service for better separation of concerns

---

📊 Overall Assessment

Rating: ✅ Approve with Minor Suggestions

This PR successfully addresses a real data consistency issue with a clean, well-tested implementation. The code follows established patterns and includes excellent test coverage. The suggested improvements are minor and don't block the core functionality.

Key Strengths: Problem clarity, solution elegance, comprehensive testing
Key Concerns: Performance monitoring, error context enhancement

The implementation correctly handles the sub-agent ID renaming scenario and maintains data integrity across tool relations. This is solid engineering work that addresses a legitimate bug.

---

*Reviewed as part of PR #1636 | *