fix: ensure consistent graph descriptions across all API endpoints

[amikofalvy]

Summary

Fixes inconsistent graph descriptions between different API endpoints where some endpoints returned fallback patterns instead of the stored description.

Linear Issue: PRD-4654
Linear URL: https://linear.app/inkeep/issue/PRD-4654/discrepancy-in-graph-description-between-endpoints

Problem

• All graphs endpoint (/tenants/{tenantId}/projects/{projectId}/agent-graphs): Returned stored description: "this is my graph"
• Single graph endpoint and A2A agent discovery: Could return fallback pattern: "Agent graph My graph"

The discrepancy was caused by:

1. Missing description field handling in CRUD POST/PUT endpoints
2. Fallback logic in A2A agent card creation

Changes

Fixed CRUD Endpoints

• ✅ POST /agent-graphs: Now includes description field when creating graphs
• ✅ PUT /agent-graphs/{id}: Now includes description field when updating graphs

Fixed A2A Agent Discovery

• ✅ Removed fallback pattern: Changed dbGraph.description || \Agent graph: ${dbGraph.name}`todbGraph.description || ''`
• ✅ Consistent empty handling: Empty descriptions now consistently return empty string instead of generated text

Added Comprehensive Tests

• ✅ Description consistency tests: Verify all endpoints return identical descriptions
• ✅ Empty description handling: Ensure consistent behavior for null/empty descriptions
• ✅ No fallback patterns: Confirm removal of "Agent graph" fallback text

Result

All graph-related endpoints now return consistent descriptions that match what's stored in the database:

• ✅ List graphs endpoint
• ✅ Single graph endpoint
• ✅ Full graph endpoint
• ✅ A2A agent discovery endpoint

Test Plan

• All existing tests pass
• New description consistency tests pass
• TypeScript compilation succeeds
• Build process completes successfully

Closes: PRD-4654

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Preview	Comments	Updated (UTC)
agents-manage-api	Ready	Preview	Comment	Sep 25, 2025 5:33pm
agents-manage-ui	Ready	Preview	Comment	Sep 25, 2025 5:33pm
agents-run-api	Ready	Preview	Comment	Sep 25, 2025 5:33pm

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
agents-docs	Skipped			Sep 25, 2025 5:33pm

[claude]

Claude finished @amikofalvy's task —— View job

---

Code Review Complete ✅

Technical Review Summary:

This PR addresses a legitimate inconsistency issue where different API endpoints were returning different descriptions for the same agent graph. The fix is well-implemented and comprehensive.

Strengths

✅ Problem Identification & Solution Design

• Clear problem statement: different endpoints returned inconsistent descriptions (stored vs. fallback patterns)
• Comprehensive solution addressing all affected endpoints
• Proper root cause analysis identifying missing field handling and fallback logic

✅ Code Quality & Implementation

• Clean, minimal changes that directly address the issue
• Follows existing patterns and conventions
• Proper handling of optional fields with explicit description: validatedBody.description
• Consistent approach across both POST and PUT endpoints

✅ Testing Strategy

• Comprehensive test coverage with 123 new lines of tests
• Tests both the positive case (consistent descriptions) and edge cases (null/empty descriptions)
• Integration tests covering all affected endpoints
• Validation that fallback patterns are properly removed

Areas for Consideration

⚠️ Schema Validation Completeness
The current implementation assumes AgentGraphApiInsertSchema and AgentGraphApiUpdateSchema properly validate the description field. I recommend verifying the schema definitions include appropriate validation:

// Worth checking: do these schemas properly validate description?
AgentGraphApiInsertSchema.extend({ description: z.string().optional() })
AgentGraphApiUpdateSchema.extend({ description: z.string().optional() })

⚠️ Database Layer Consistency
The fix correctly handles description in the API layer, but consider whether any caching layers or other data access patterns might still use fallback logic. The change to dbGraph.description || '' is correct but verify this pattern is consistently applied across all graph description access points.

⚠️ Backward Compatibility
The change from dbGraph.description || \Agent graph: ${dbGraph.name}`todbGraph.description || ''` is a breaking change in behavior. While this is the correct fix, ensure:

• Existing clients can handle empty descriptions appropriately
• No other parts of the system depend on the fallback pattern
• Documentation is updated to reflect the new behavior

Architecture Assessment

✅ Consistent Data Contracts

• All endpoints now return identical descriptions from the same data source
• Proper separation of concerns: API layer handles field mapping, data layer provides raw values
• No unnecessary data transformations or business logic in data access layer

✅ API Design Principles

• RESTful consistency across CRUD operations
• Predictable behavior: same data, same response across endpoints
• Proper handling of optional fields without unexpected defaults

Customer Impact

✅ Positive Impact

• Eliminates confusing inconsistencies in API responses
• More predictable behavior for client applications
• Better developer experience with reliable data contracts

⚠️ Potential Breaking Change
Applications expecting the fallback "Agent graph: {name}" pattern will now receive empty strings instead. This is the correct behavior but may require client-side updates.

Recommendations

1. Verify Schema Coverage: Double-check that validation schemas properly handle the description field
2. Consider Migration: For graphs that currently rely on fallback patterns, consider a data migration to populate actual descriptions
3. Documentation Update: Update API documentation to clarify description field behavior
4. Monitor Deployment: Watch for any client-side issues after deployment due to the behavior change

Final Assessment

This is a well-executed fix for a real API consistency issue. The implementation is clean, properly tested, and follows good engineering practices. The comprehensive test suite gives confidence that the fix works as intended across all affected endpoints.

Recommended Action: ✅ Approve with the minor recommendations above for completeness.

---

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity.
It will be closed in 7 days if no further activity occurs.

If this PR is still relevant:

• Rebase it on the latest main branch
• Add a comment explaining its current status
• Request a review if it's ready

Thank you for your contributions!

[github-actions]

This pull request has been automatically closed due to inactivity.

If you'd like to continue working on this, please:

1. Create a new branch from the latest main
2. Cherry-pick your commits or rebase your changes
3. Open a new pull request

Thank you for your understanding!