Files
twenty/packages/twenty-server/test/integration/graphql/suites/agent/agent.integration-spec.ts
T
Félix Malfait e7ebf51e50 Replace agent handoff system with planning-based router (#16003)
## Overview

This PR replaces the dynamic agent handoff system with a more
predictable planning-based router that decides upfront how to handle
multi-agent coordination.

## Major Changes

### 🔄 Architecture Shift: Handoffs → Planning

**Removed:**
- `AgentHandoffEntity` and handoff tracking system
- `AgentHandoffService` and `AgentHandoffExecutorService`
- Dynamic agent-to-agent transfers during execution
- Handoff tool generation and description templates

**Added:**
- `AiRouterService` with two strategies: `simple` (single agent) and
`planned` (multi-agent)
- `AgentPlanExecutorService` for executing multi-step plans
- Plan validation (cycle detection, dependency resolution)
- `UnifiedRouterResult` type with discriminated union

### 🤖 New Standard Agents

Added two new specialized agents:
- **Researcher Agent**: Web search, fact-finding, competitive
intelligence
- **Code Agent**: TypeScript function generation for serverless
workflows

### 🏗️ Router Refactoring (Latest)

Split router responsibilities into focused services:
- `AiRouterStrategyDeciderService`: Decides simple vs planned strategy
- `AiRouterPlanGeneratorService`: Generates and validates execution
plans
- `AiRouterService`: Coordinates between services (reduced from 426→275
lines)

### ⚙️ Configuration Improvements

- Added `outputStrategy` to agent definitions (`direct` vs `synthesize`)
- Removed hardcoded special cases for workflow-builder
- Added `plannerModel` field to workspace entity
- Increased `MAX_STEPS` from 10 to 25 for complex workflows

### 📝 Agent Prompt Refinements

Significantly simplified prompts for better clarity:
- Workflow Builder: 51→36 lines
- Helper: 49→28 lines
- Data Manipulator: Enhanced with sorting guidance

### 🔍 Enhanced Debugging

- Plan reasoning and step count in data message parts
- Router debug info with token usage tracking
- Better logging throughout execution pipeline

## Benefits

1. **Simpler Mental Model**: Router decides upfront vs dynamic transfers
2. **Better Predictability**: Users see the plan before execution
3. **Cleaner Architecture**: SRP with focused services
4. **Configuration Over Code**: Agent behavior via config, not hardcoded
logic
5. **Plan Validation**: Catches invalid dependencies and cycles

## Migration Notes

- Database migration removes `agentHandoff` table
- Adds `plannerModel` column to workspace table
- No API breaking changes (agent endpoints unchanged)

## Testing

- Integration tests updated to remove handoff dependencies
- Agent tool test utilities simplified
- Plan validation covered by new logic

## Next Steps (Future PRs)

- Parallel execution of independent plan steps
- Dynamic re-planning based on results
- Plan caching for common routing patterns
- Error recovery strategies in plan executor
2025-11-25 12:10:14 +01:00

212 lines
6.6 KiB
TypeScript

import { Test, type TestingModule } from '@nestjs/testing';
import { getRepositoryToken } from '@nestjs/typeorm';
import { AiAgentRoleService } from 'src/engine/metadata-modules/ai-agent-role/ai-agent-role.service';
import { AgentChatService } from 'src/engine/metadata-modules/ai-chat/services/agent-chat.service';
import { AgentEntity } from 'src/engine/metadata-modules/ai-agent/entities/agent.entity';
import {
AgentException,
AgentExceptionCode,
} from 'src/engine/metadata-modules/ai-agent/agent.exception';
import { AgentResolver } from 'src/engine/metadata-modules/ai-agent/agent.resolver';
import { AgentService } from 'src/engine/metadata-modules/ai-agent/agent.service';
import { PermissionsService } from 'src/engine/metadata-modules/permissions/permissions.service';
import { RoleTargetsEntity } from 'src/engine/metadata-modules/role/role-targets.entity';
// Mock the agent service
jest.mock('../../../../../src/engine/metadata-modules/ai-agent/agent.service');
// Mock the guards and decorators
jest.mock('../../../../../src/engine/guards/feature-flag.guard', () => ({
FeatureFlagGuard: jest.fn().mockImplementation(() => ({
canActivate: jest.fn().mockReturnValue(true),
})),
RequireFeatureFlag: () => jest.fn(),
}));
jest.mock('../../../../../src/engine/guards/workspace-auth.guard', () => ({
WorkspaceAuthGuard: jest.fn().mockImplementation(() => ({
canActivate: jest.fn().mockReturnValue(true),
})),
}));
describe('agentResolver', () => {
let agentService: AgentService;
let agentResolver: AgentResolver;
let module: TestingModule;
beforeAll(async () => {
// Create a testing module with mocked dependencies
module = await Test.createTestingModule({
providers: [
AgentResolver,
{
provide: AgentService,
useValue: {
findOneAgent: jest.fn(),
updateOneAgent: jest.fn(),
},
},
{
provide: getRepositoryToken(AgentEntity),
useValue: {
find: jest.fn(),
findOne: jest.fn(),
save: jest.fn(),
softDelete: jest.fn(),
},
},
{
provide: getRepositoryToken(RoleTargetsEntity),
useValue: {
findOne: jest.fn(),
},
},
{
provide: AgentChatService,
useValue: {
createThread: jest.fn(),
},
},
{
provide: AiAgentRoleService,
useValue: {
assignRoleToAgent: jest.fn(),
removeRoleFromAgent: jest.fn(),
},
},
{
provide: PermissionsService,
useValue: {
userHasWorkspaceSettingPermission: jest
.fn()
.mockResolvedValue(true),
},
},
],
}).compile();
// Get the mocked services from the module
agentService = module.get<AgentService>(AgentService);
agentResolver = module.get<AgentResolver>(AgentResolver);
});
afterAll(async () => {
if (module) {
await module.close();
}
});
beforeEach(() => {
jest.clearAllMocks();
});
describe('findOneAgent', () => {
const testAgentId = 'test-agent-id';
const workspaceId = 'test-workspace-id';
const mockAgent = {
id: testAgentId,
name: 'Test Agent for Find',
description: 'A test agent for find operations',
prompt: 'You are a test agent for finding.',
modelId: 'gpt-4o',
roleId: null,
createdAt: new Date(),
updatedAt: new Date(),
};
it('should find agent by ID successfully', async () => {
// Mock the findOneAgent method to return a mock agent
(agentService.findOneAgent as jest.Mock).mockResolvedValueOnce(mockAgent);
// Call the resolver directly
const result = await agentResolver.findOneAgent({ id: testAgentId }, {
id: workspaceId,
} as any);
// Verify the service was called with the correct parameters
expect(agentService.findOneAgent).toHaveBeenCalledWith(workspaceId, {
id: testAgentId,
});
// Verify the result matches our expectations
expect(result).toBeDefined();
expect(result.id).toBe(testAgentId);
expect(result.name).toBe('Test Agent for Find');
});
it('should throw an error for non-existent agent', async () => {
const nonExistentId = '00000000-0000-0000-0000-000000000000';
// Mock the findOneAgent method to throw an exception
(agentService.findOneAgent as jest.Mock).mockRejectedValueOnce(
new AgentException(
`Agent with id ${nonExistentId} not found`,
AgentExceptionCode.AGENT_NOT_FOUND,
),
);
// Call the resolver and expect it to throw
await expect(
agentResolver.findOneAgent({ id: nonExistentId }, {
id: workspaceId,
} as any),
).rejects.toThrow(AgentException);
});
});
describe('updateOneAgent', () => {
const testAgentId = 'test-agent-id';
const workspaceId = 'test-workspace-id';
const updatedAgent = {
id: testAgentId,
name: 'Updated Test Agent Admin',
description: 'Updated description',
prompt: 'Updated prompt for admin',
modelId: 'gpt-4o-mini',
roleId: null,
createdAt: new Date(),
updatedAt: new Date(),
};
it('should update an agent successfully', async () => {
// Mock the updateOneAgent method to return the updated agent
(agentService.updateOneAgent as jest.Mock).mockResolvedValueOnce(
updatedAgent,
);
// Call the resolver directly
const result = await agentResolver.updateOneAgent(
{
id: testAgentId,
name: 'Updated Test Agent Admin',
description: 'Updated description',
prompt: 'Updated prompt for admin',
modelId: 'gpt-4o-mini',
},
{ id: workspaceId } as any,
);
// Verify the service was called with the correct parameters
expect(agentService.updateOneAgent).toHaveBeenCalledWith(
{
id: testAgentId,
name: 'Updated Test Agent Admin',
description: 'Updated description',
prompt: 'Updated prompt for admin',
modelId: 'gpt-4o-mini',
},
workspaceId,
);
// Verify the result matches our expectations
expect(result).toBeDefined();
expect(result.id).toBe(testAgentId);
expect(result.name).toBe('Updated Test Agent Admin');
expect(result.description).toBe('Updated description');
expect(result.prompt).toBe('Updated prompt for admin');
expect(result.modelId).toBe('gpt-4o-mini');
});
});
});